@flood-md/agent 0.2.8 → 0.2.10

package/DESIGN.md

@@ -1,4 +1,4 @@
-# Flood design system · 0.2.8
+# Flood design system · 0.2.10
 
 ListBox owns native required validation for accepted selection. Use its
 description/message/status props rather than duplicating feedback markup. Visual
@@ -34,14 +34,15 @@ The installed entry is .agents/skills/flood-ui/SKILL.md; its references live und
 accessibility, customization or verification reference. flood/manifest.json maps
 package sources to those installed paths; flood/rules.json indexes observable
 checks. In the Flood repository the corresponding sources are packages/agent/.
-This bundle belongs to 0.2.7; older installations keep their matching guide set.
+This bundle belongs to the package version in its heading; older installations
+keep their matching guide set.
 
 React + TypeScript and Next.js App Router. Use this guide with matching installed
 Flood packages and flood.json. The source repository's release status does not
 grant permission to publish or assume a version is available on npm.
 
-This guide covers the supported exports in 0.2.7 and their layout refinements. Confirm
-the matching installed declarations before using APIs absent from older versions.
+This guide describes the matching package's capabilities and layout contracts.
+Confirm its installed declarations before using APIs absent from older versions.
 
 ## Connect
 
@@ -440,3 +441,24 @@ and UploadItem place it with the filename, reserving the next line for status or
 supporting text. Filename extensions are display hints only, never validation.
 Override with format or hide the format using format=null; do not infer upload
 safety or MIME permissions from a visible chip.
+
+## Form hierarchy
+
+Named field labels use field-label typography, with space-1 to their controls.
+Parent Grid/Stack owns row and group separation. Keep shared tracks across related
+rows instead of independently narrowing numeric fields. Dialog uses dialog-title
+typography and space-6 before its body; do not add that inset a second time.
+Fieldset defaults to a compact choice caption; legendSize="section" opts into
+group-title typography for a necessary independent section. A short form can
+omit inner headings. See the routed hierarchy workflow for reading order, rhythm
+and actual geometry review. DatePicker keeps a readable 20rem calendar panel
+minimum when space permits, while honoring viewport collision constraints.
+
+## Record information hierarchy
+
+Select visible attributes from recognition, comparison and action needs, not
+from every available data property. For list/detail work use the routed records
+workflow: identity/summary, lifecycle state, category, priority and dates have
+different roles. Named comparison columns are preferable to drifting trailing
+values when several attributes must be compared. Metadata may be necessary even
+when an inspector flags it; preserve useful content and evaluate its placement.

package/README.md

@@ -1,10 +1,48 @@
 # @flood-md/agent
 
 Version-matched guidance for Flood React/Next.js projects. Read the installed
-contract before composing screens. The 0.2.8 reference bundle includes spacing
+contract before composing screens. The 0.2.10 reference bundle includes spacing
 guidance, routing and observable rules. These files grant
 no authority to modify external services.
 
+The optional `@flood-md/agent/inspect` export supplies inspectRenderedUI for
+browser evaluation in local verification tooling. It reads the current rendered
+DOM without mutation/network access and returns bounded observations, copy and
+field geometry. See [rendered review](references/rendered-review.md) for execution,
+privacy, limits and contextual review. The main knowledge-reader entry remains
+Node-only. An empty observation list does not certify an interface's quality.
+The same optional entry exports inspectSourceUI for bounded text observations
+of host-owned JSX/CSS. It suggests owner review for native dialogs/controls and
+custom layouts without reading files or executing source. Text matches can be
+false positives or miss indirect code; see the rendered-review reference.
+
+The package also exposes a Node-only, read-only knowledge API with TypeScript
+declarations. No model provider, network service or MCP runtime is required.
+
+```ts
+import {createKnowledgeReader} from '@flood-md/agent';
+const reader = createKnowledgeReader();
+const context = await reader.info();
+const page = await reader.list({kind: 'component', search: 'table'});
+const material = await reader.read('component:data-table');
+```
+
+Follow nextCursor/nextOffset when present. Metadata is bounded separately from
+material bodies; a selected body is checked against the matching package catalog.
+The CLI adds host-version checks and preservation of project-owned guide copies.
+knowledge.json contains semantic annotations; build generates dist/catalog.json
+from the same canonical components, token manifest, guides and recipes used by
+the website. Do not hand-edit generated hashes or duplicate component contracts.
+See [Agent knowledge](../../docs/agent-knowledge.md) for groups, capabilities,
+prerequisites, read budgets, compatibility and customization behavior.
+
+The source bundle also includes thirteen routed workflows for the existing dark base:
+composition, hierarchy, spacing, foundations, accessibility, forms, overlays, navigation,
+data display, records, feedback, interface content and verification. The lightweight flood-ui entry selects
+relevant skills; nested folders do not imply independent automatic discovery.
+workflows.json describes applicability. rules.json describes observable checks;
+neither is a completed component-audit report or executable enforcement engine.
+
 | Source | Role |
 | --- | --- |
 | DESIGN.md | Shared versioned UI/component contract |
@@ -18,6 +56,7 @@ no authority to modify external services.
 | references/verification.md | Evidence before reporting completion |
 | rules.json | Stable rule IDs with conditions, sources and observable checks |
 | manifest.json | Source → installed-path mapping used by the CLI |
+| workflows.json | Component-family applicability and routed full-skill sources |
 
 CLI init copies every manifest entry into an unused owned path. Doctor checks
 expected regular files without linked destinations. Neither tool rewrites host

package/SKILL.md

@@ -10,6 +10,12 @@ the project root. Installed declarations decide which APIs exist. A newer web
 page or repository example does not add exports to an older package. Run the
 matching installed CLI's doctor when versions or guide files are uncertain.
 
+The matching CLI's info command reports project/bundle scope and capabilities.
+Use catalog to discover compact metadata by kind/group, then read a selected ID.
+Read [knowledge discovery](references/knowledge.md) when using these commands or
+extending Flood's knowledge. Complete paginated selected instructions before
+acting; metadata, related links and capability declarations are not executed checks.
+
 Import @flood-md/react/styles.css once; compose new dark interfaces in FloodRoot.
 Use Flood's existing components before introducing a local adapter. Keep user
 scope and host conventions; missing Flood behavior must be stated rather than
@@ -17,14 +23,45 @@ invented as a package API. No external component library or parallel token syste
 
 ## Read only the relevant reference
 
+For a new screen, read the composition and interface-content workflows below
+before the first JSX. Discover owners in the installed catalog before choosing
+familiar low-level controls. Keep a short role → selected component → consulted
+contract record in the development notes, outside the interface. A supplied guide
+or a remembered export is not evidence that its contract was read.
+
+Before delivery, review the actual screen against those choices and the content
+workflow. Optional subtitle, description and hint slots start empty; fill one
+only for information the user needs beyond the title or control itself.
+
+For a new screen or composed form, read the hierarchy workflow to choose visual
+roles, shared tracks and relationship spacing. For a composed form, also read the forms workflow's grouping section; independent
+per-row grids do not establish a coherent hierarchy. For icon-bearing controls,
+use the foundations workflow. During browser verification use the optional
+[rendered review observer](references/rendered-review.md) and review its findings.
+It cannot replace the separate copy and grouping decisions.
+For record lists or details, read the records workflow before assigning metadata
+to slots. Record each field's recognition/comparison/action purpose and list/detail
+placement outside the interface; an available slot is not a reason to fill it.
+For save, upload or other fallible operations, read the feedback workflow too:
+message lifetime belongs to the operation/record, not merely the page's Alert.
+
 | Work | Read next | Required result |
 | --- | --- | --- |
+| Introducing or editing interface copy, labels, hierarchy or adapting a reference | [Interface content skill](references/flood-interface-content/SKILL.md) | Necessary, accurate content with a clear job; no invented capabilities or redundant narration |
 | Component, composite, website or playground UI | [Composition skill](references/flood-composition/SKILL.md) | Reused primitives; missing small capabilities implemented before composites |
 | New screen, layout or form | [Composition](references/composition.md) | Existing primitives, correct host width and form ownership |
-| Spacing, density, nested geometry or shifting previews | [Spacing](references/spacing.md) | Measured visual relationships and nonoverlapping interactive areas |
-| Keyboard, validation, names or states | [Accessibility](references/accessibility.md) | Real interaction and associations preserved |
-| Brand, colors or typography | [Customization](references/customization.md) | Scoped semantic overrides; unchanged behavior |
-| Completion, regression or upgrade review | [Verification](references/verification.md) | Checks and limits reported against the actual host |
+| Task/group/field hierarchy, flat forms or inconsistent row tracks | [Hierarchy skill](references/flood-hierarchy/SKILL.md) | Distinct roles, shared control edges and deliberate vertical rhythm |
+| Spacing, density, nested geometry or shifting previews | [Spacing skill](references/flood-spacing/SKILL.md) | Measured visual relationships and nonoverlapping interactive areas |
+| Existing dark surfaces, type, control and icon sizing | [Foundations skill](references/flood-foundations/SKILL.md) | Correct semantic roles and coherent consumers |
+| Keyboard, names, focus, perception or reflow | [Accessibility skill](references/flood-accessibility/SKILL.md) | Real interaction and associations preserved |
+| Field ownership, validation, submission and reset | [Forms skill](references/flood-forms/SKILL.md) | Actual form values and accepted/refused transitions |
+| Popup, dialog, drawer or nested layer | [Overlays skill](references/flood-overlays/SKILL.md) | Appropriate geometry, dismissal and focus ownership |
+| Destinations, panels, disclosure or hierarchy | [Navigation skill](references/flood-navigation/SKILL.md) | Navigation, selection and expansion kept distinct |
+| Record lists/details, crowded metadata, status/category/priority distinctions | [Records skill](references/flood-records/SKILL.md) | Decision-relevant attributes, clear semantics and stable scan positions |
+| Tables, lists, cards, files and long content | [Data display skill](references/flood-data-display/SKILL.md) | Meaningful structures and reachable overflow |
+| Status, progress, alerts, loading or empty content | [Feedback skill](references/flood-feedback/SKILL.md) | Honest operation state with one announcement owner |
+| Brand or deliberate semantic overrides | [Customization](references/customization.md) | Scoped semantic overrides; unchanged behavior |
+| Completion, stabilization or regression review | [Verification skill](references/flood-verification/SKILL.md) | Checks and limits reported against the actual host |
 | Decide which document governs a change | [Routing and sources](references/routing.md) | Source of truth and prerequisites identified |
 
 The project-root flood/rules.json lists stable rule IDs and their observable
@@ -32,5 +69,10 @@ checks; it is an index, not executable policy. At completion report which checks
 ran, their result and any unverified behavior. Doctor checks installation only.
 Guidance cannot guarantee an agent's compliance or certify application accessibility.
 
+The workflow index lists component-family applicability, not a requirement to load
+every skill or proof that a component passed its checks. These specialized skills
+are routed references inside flood-ui; independent discovery of nested folders
+is not assumed. Resolve sources through the installed manifest when needed.
+
 Preserve existing instructions and customized guides. This skill authorizes no
 deployment, deletion, external messages or sending host source to other services.