Agent knowledge
Versioned discovery, selected reading and knowledge growth safeguards.
Flood 0.2.10 adds a versioned read-only catalog and reader. Use the CLI matching the project's flood.json; source availability does not prove npm publication. The same package sources build the website, CLI results and agent instructions.
Discover, then read
These commands return JSON and do not install dependencies, edit files, execute skill text or contact a Flood server. The package runner may fetch the CLI if it is not installed locally; keep its version deliberate. Existing project and agent instructions remain authoritative.
info reports actual installed package versions, the configured guide version, framework detection, catalog identity and capability declarations. A version mismatch prevents catalog/read from serving an ambiguous guide train. A bundle-only result describes the CLI's bundle; it is not proof that the host has installed Flood or imported its stylesheet. doctor remains the installation check.
Material types and groups
Stable IDs distinguish workflows, references, components, recipes, guides and semantic token records. Groups organize Foundations, Composition, Interaction, Data & feedback, Quality and existing Motion tokens. They are navigation labels; one task can use several groups. Current capability gaps are explicit in info.
For example, page-transition workflows and additional foundation themes are not supplied. Existing motion tokens do not create a PageTransition export. Scoped brand overrides do not add a brand Button variant. Read reference:customization and the actual token records before changing semantic roles.
Bounded output and version identity
catalog accepts --kind, --group, --search, --limit and --cursor. Search matches literal metadata case-insensitively; it is not model-based intent routing. The default limit is 12, maximum 50, and each metadata page is capped at 16 KiB. If truncated is true, follow nextCursor. A changed query or catalog invalidates that cursor. This remains bounded as the number of components increases.
read accepts --offset and --length. Its default is 10,000 Unicode code points, maximum 40,000; follow nextOffset to finish a selected instruction. Related links are limited to 32 per read; use --links-offset with nextLinksOffset for more. Required prerequisites are separate from optional links. A workflow applying to many components does not require reading all of them.
The reader checks schema, relationships, package version and selected content integrity. It reads only the selected body. The catalog is capped at 8 MiB and each material at 1 MiB. Limits fail explicitly; they are not silent omissions. The current protocol permits up to 16 semantic groups, 32 capability declarations, 16 direct prerequisites and 256 related links per material. Prerequisite depth is limited to 32. Expanding these limits is a reviewed protocol decision, not a reason to delete safeguards when the catalog grows.
Customized project guides
For material copied by init, read defaults to the existing project guide. The response identifies source=project, its hash and customized status. Other materials come from the matching package. Missing or linked project guides fail explicitly; they are not silently replaced by upstream instructions.
Use --source package to compare canonical upstream content. It never overwrites customized files. flood/catalog.json is an installed snapshot, not executable configuration or permission to redirect reads. Instructions cannot authorize external actions that the user did not request.
API and contribution checks
The Node API exports createKnowledgeReader and validateKnowledgeCatalog from @flood-md/agent, with matching TypeScript declarations. It has info(), list(query) and read(id, range) methods and performs no network operations. Pass an explicit package root when reading an isolated package; otherwise it uses its own package.
Contributors edit canonical code, guides and knowledge.json annotations. Build regenerates content and hashes; stale/unmapped workflows, unknown imports, duplicate IDs, broken guidance links and prerequisite cycles stop compilation. The compatibility fixture records established public IDs. Growth tests exercise 5,000 metadata entries, pagination, stale cursors, selected-content integrity and host customization. Clean tarball and browser checks verify the consumer boundary. None of these checks independently proves model routing accuracy, general accessibility or visual quality.