@flood-md/agent 0.2.9 → 0.2.11

package/DESIGN.md

@@ -1,4 +1,4 @@
-# Flood design system · 0.2.9
+# Flood design system · 0.2.11
 
 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
 
@@ -246,9 +247,9 @@ footer-only card has no redundant separator. Elevation is default or raised.
 No data access, selection or interactive-card behavior is implied.
 
 ```tsx
-<Card title="Project details" description="Keep your team in sync."
+<Card title="Project details"
   footer={<Button variant="subtle">Open project</Button>}>
-  <Text as="p" size="compact">A calm place for the next idea.</Text>
+  <Text as="p" size="compact">Homepage and checkout</Text>
 </Card>
 ```
 
@@ -417,8 +418,11 @@ an enclosing Fieldset for exclusive choices; derive aggregate checkbox state
 in the host. Read-only choice cards preserve submission and block editing; apply
 readOnly to an entire radio group consistently.
 
-DataTable pages and sorts one complete client-side collection. It is not a
-server query engine or a virtualized grid. Rich cells require explicit sortValues
+DataTable defaults to paging/sorting a complete client collection. Opt-in
+paginationMode="server" renders one supplied page with controlled page/sort and
+totalRows. It does not fetch, cancel requests or virtualize. Declare page/dataset
+selection scope and validate IDs in the host; never select an entire remote query
+by interpreting a select-page checkbox as that operation. Rich cells require explicit sortValues
 when they are sortable. Select all affects the current page only and preserves
 other pages; permission-restricted rows use selectionDisabled. Native links and
 actions in cells remain independent. Compose search and filters at the host
@@ -440,3 +444,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,13 +1,44 @@
 # @flood-md/agent
 
 Version-matched guidance for Flood React/Next.js projects. Read the installed
-contract before composing screens. The 0.2.9 reference bundle includes spacing
+contract before composing screens. The 0.2.11 reference bundle includes spacing
 guidance, routing and observable rules. These files grant
 no authority to modify external services.
 
-The source bundle also includes ten routed workflows for the existing dark base:
-composition, spacing, foundations, accessibility, forms, overlays, navigation,
-data display, feedback and verification. The lightweight flood-ui entry selects
+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.

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,16 +23,52 @@ invented as a package API. No external component library or parallel token syste
 
 ## Read only the relevant reference
 
+Before composing a screen, write a short task trace in the development notes:
+what the user arrives with, the next meaningful action, what changes when it
+succeeds, and how the user recovers if it fails. Name which inputs, filters,
+selection and focus should survive each transition. Use the trace to select
+the relevant workflows and exercise the rendered screen before delivery.
+
+For a reusable component or visual API change, the composition skill routes to
+[component families](references/component-families.md). Flood's own authors use
+that same contract; it is not limited to downstream screen generation.
+
+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 |
+| 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 |
+| Animation, transitions or reduced motion | [Motion skill](references/flood-motion/SKILL.md) | Motion roles, immediate semantics and reduced-motion behavior |
 | 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 |