@flood-md/agent 0.2.9 → 0.2.10

package/references/flood-forms/SKILL.md

@@ -11,6 +11,12 @@ ownership. Read the matching DateField/DateTimePicker component guide for its
 specific civil-value and draft contract; [accessibility](../accessibility.md)
 documents associations and feedback.
 
+For an ordinary business date field, prefer DatePicker so users can both type and
+choose visually. DateField is the lower-level segmented editor without a popup;
+choose it for an explicit entry-only interaction or inside a composition that
+already supplies Calendar. Do not silently omit the calendar just because the
+brief did not enumerate every affordance of choosing a date.
+
 ## Assign ownership
 
 - Field supplies label/description/error associations through its render props;
@@ -31,6 +37,47 @@ documents associations and feedback.
   Host validation decides the error and useful message. Keep native constraints,
   invalid focus and the accessible message association coherent.
 
+For visual roles and rhythm, read the [hierarchy skill](../flood-hierarchy/SKILL.md).
+Fieldset legendSize="section" is for an independent section; a short form may
+need no inner heading. Field labels and values keep their documented sizes.
+
+## Group before laying out fields
+
+Choose the form's reading order and semantic groups before placing controls in
+columns. Establish shared outer tracks, gap and group padding. Use a single Grid for
+related rows; do not narrow one numeric field in only one row merely because its
+value is short. Preserve corresponding vertical edges before optimizing widths. Related groups
+should share those tracks: do not independently choose a four-column grid above
+two columns below and assume their edges align. A group may span the whole layout
+when its content needs it; not every field should have the same width.
+
+For Flood record/settings forms without a denser host requirement, start with
+at most two field tracks per semantic group. Four metadata fields become two
+pairs rather than an automatic four-field strip. Use one track for a narrow group
+or long field. A denser table editor, filter toolbar or explicit host design is
+a different context; record why its structure needs more tracks.
+
+For two peer groups, use two equal outer tracks and subdivide each consistently
+when a group contains short related fields. A pair of two-field groups can read
+more clearly than four unrelated columns. This is a pattern to evaluate, not a
+rule that every form has two columns or an invoice-specific template.
+
+Keep a group's title, controls and supporting message together in reading and DOM
+order. Distinguish page, group and field roles without adding headings merely to
+fill containers. Compare shared leading/trailing edges and gutters in the rendered
+form, including absent descriptions, long labels and changed field values.
+
+Measure the controls' content edges, not only the Grid boxes. A full-width padded
+Surface containing two tracks and two separately padded Surfaces can use identical
+Grid props while their actual controls differ by one surface inset. Nested padding
+must participate in the same track budget. Compare corresponding first/second
+control starts and widths across those groups; matching outer containers is not
+sufficient. Do not insert an empty grid child merely to occupy an unexplained gap.
+For a concrete starting structure, discover recipe:grouped-form in the installed
+catalog. It demonstrates shared tracks and two-field peer groups in a workspace
+form. Adapt its grouping to the host; do not copy its business content or add
+unrequested sample records.
+
 ## Exercise transitions, not just props
 
 Check entry, clear, incomplete drafts, invalid input, accepted/refused controlled
@@ -41,5 +88,7 @@ representation genuinely requires it. Do not silently replace user edits.
 FileInput cannot receive a fabricated FileList or ordinary controlled text value.
 Separate selection from upload transport and progress. Calendar/date/time controls
 represent their documented civil values; do not infer a timezone or server save.
-Show a real success only after the host operation succeeds. In a local example,
-state explicitly that changes are local.
+Show a real success only after the host operation succeeds. Explain consequential
+storage limits once where they matter; a local example does not require a banner
+or repeated captions about its implementation. Follow the interface-content
+workflow for placement and wording.

package/references/flood-foundations/SKILL.md

@@ -27,6 +27,13 @@ applies the existing dark base; it does not start a palette, theme or motion red
   owns explicit artwork dimensions; IconButton owns the accessible action/target.
   A large control does not mean an unconstrained SVG or oversized supporting copy.
 
+Action icons are artwork with an explicit IconSlot size, not a plus, arrow or
+cross typed into the label. Font glyph bounds vary even at the same font size.
+Use the project's licensed icon pack or an original SVG in IconSlot; text-only
+actions can omit the icon. Keep real symbols that are content, such as currency,
+phone prefixes or mathematical expressions, as text. Inspect the actual artwork
+and its centre relative to the label at the chosen Button size.
+
 ## Evidence
 
 Trace a changed role to its consumers and compare resting, hover, selected,

package/references/flood-hierarchy/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: flood-hierarchy
+description: Establish visual hierarchy, shared form tracks and vertical rhythm in Flood screens, forms and overlays. Use when titles, groups and labels compete or a composed interface feels flat; not a fixed page template.
+---
+
+# Structure before emphasis
+
+Start with the user's task, reading order and installed component contracts.
+Distinguish the task title, genuinely independent groups, field labels, input
+values and actions before choosing their size or color. A short form may need
+only its task title and labels. Do not add a legend, subtitle, card or divider
+merely to create visual levels. Meaning comes from the interface-content workflow;
+this workflow makes that meaning visible.
+
+## Assign each relationship to its owner
+
+- Dialog owns its task heading and the body inset. Its dark title uses the
+  dialog-title role (1.25rem / 600); it is distinct from compact popup captions.
+- Field owns the label-to-control relationship: space-1 (.25rem) in the dark
+  profile. DateField/TimeField already use that relationship. Leave room between
+  independent fields instead of increasing the gap inside every label/control pair.
+- Field labels use field-label typography (.8125rem / 500) and readable primary
+  content color. Do not shrink every label or fade necessary labels to manufacture
+  hierarchy; units, required markers, errors and accessible associations remain.
+- Fieldset defaults to a compact label-sized legend for related choices. Use
+  legendSize="section" for a necessary independent form section: group-title
+  typography (1rem / 600) and space-4 before its fields. A legend is still a native
+  group label, not a new document heading level. Optional hint/choice relationships
+  keep their compact component-owned spacing.
+- Grid owns common tracks; Stack and Inline own relationships between fields,
+  groups and actions. Never duplicate component anatomy with styled text.
+
+These are installed recipe defaults, not permission to use missing APIs in an
+older package or to override private selectors in a host stylesheet.
+
+## Establish a shared frame
+
+Use one Grid for related rows that should share vertical edges. Two equal tracks
+are a useful starting point for four short fields; long names and descriptions
+can span the width. Numeric content being short does not by itself justify a
+narrower track in only one row. If a specialized width is necessary, preserve the
+common grid or deliberately separate that group and check its visual relationship.
+Do not repair a whole-frame mismatch with manual widths on individual controls.
+
+Choose the user's reading order first. In an ordinary date/time form, a pair of
+calendar and time controls can share tracks with a later pair of duration/status
+controls. This is an example, not an appointment-specific template. Independent
+semantic grouping can justify another order. Do not turn every group into a box.
+
+## Choose a rhythm, not a uniform gap
+
+For an ordinary desktop form, start with space-6 between field rows and space-8
+between independent groups or before the closing action row. The Dialog body
+inset is already space-6: do not add the same inset again to the first child.
+Keep a label nearer its control than the next field and a group title nearer
+its own fields than the next group. Dense filters, table editors and choice lists
+have different budgets; apply their component recipes instead of spreading this
+form rhythm everywhere.
+
+Treat action order/alignment as part of the task. An end-aligned cancel/primary
+pair can finish a short desktop dialog clearly. This is not a universal order:
+respect host conventions, direction, destructive confirmation and keyboard flow.
+Do not add a footer surface or separator unless it resolves a real boundary.
+
+Record lists and details need an information budget as well as type hierarchy.
+Use the [records workflow](../flood-records/SKILL.md) for metadata placement,
+comparison columns and status/category/priority meanings; do not give every
+attribute equal visual emphasis.
+
+## Verify the relationships
+
+Read the actual title/group/label styles; inspect the rendered result rather
+than comparing font-size declarations alone. Check complete text and long values,
+not only empty inputs. Measure the left/right edges of corresponding controls
+across rows, including nested padding and optional fields. A shared outer Grid
+alone is not proof that the input edges align.
+
+At the host's desktop baseline include 1280px with 24px root text as well as
+normal 1280/1440px views. Ensure the final action remains reachable if the dialog
+needs to scroll. Open actual date/selection popups: a calendar needs readable
+content width even when its anchor is narrow; a selection list has a different
+width contract. Keep viewport collision limits and nested Escape/focus ownership.
+
+Report the consequential choices and actual evidence outside the product UI.
+An empty inspector result does not establish hierarchy, necessary copy or visual
+quality. Preserve a failed clean run; improve the library/guidance owner before
+starting a fresh evaluation, rather than editing the historical result.

package/references/flood-interface-content/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: flood-interface-content
+description: Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents.
+---
+
+# Edit the information, then the wording
+
+Read the task, existing product vocabulary and the relevant component contracts.
+Keep the requested audience, language, surface and scope. A test host is not an
+invitation to add a product story, onboarding, promotional banners or new flows.
+User-authored records and document bodies remain data; changing interface copy
+does not authorize rewriting them.
+
+## Give every text element a job
+
+Before adding copy, identify the user's current task and state. Each visible
+string should identify an object or control, distinguish choices, supply needed
+input guidance, explain a relevant consequence, report a real state or support
+recovery in the current task/state. A fact being potentially useful someday is
+not sufficient. If its removal changes none of those, remove the element rather than
+replace it with another friendly sentence.
+
+Make the decision in context:
+
+- **Keep** a necessary label, distinction, constraint, consequence at the relevant decision or recovery step after a real failure.
+- **Rewrite** an ambiguous or inaccurate message using the product's terms.
+- **Move** secondary, occasionally needed information to a relevant help surface.
+- **Remove** duplication, routine interface narration and filler added to fill space.
+
+Do not turn this into a shortest-copy contest. A longer explanation can be the
+correct choice for an unfamiliar decision, an exceptional state or a material
+consequence of an action being considered here. An ordinary list/editor is not a
+storage-selection or data-deletion decision: do not add a standing browser/storage
+warning just because clearing browser data could lose records. Put implementation
+limits in documentation/help; explain deletion/replacement consequences before
+the applicable action and actual persistence failures when they occur.
+Do not hide essential instructions or risks behind a tooltip merely
+to make a screen quieter. Preserve accessible names and associations when reducing
+visible copy; use the component's documented hideLabel API where appropriate.
+
+## Separate prototype provenance from product state
+
+An explicitly requested local prototype or fixture-backed test app does not need
+an always-visible Demo, Prototype, Local only or Test environment badge merely
+because of its development context. Put that provenance and its implementation
+limits in the project README, test brief or review handoff. Do not fill a sidebar
+footer, header or empty region with a reminder, or replace a removed badge with
+a differently worded banner.
+
+Keep a visible distinction when it changes a decision on this surface: sample
+records mixed with real records, a meaningful selectable simulation mode, or an
+action whose effect/destination differs between environments. Place it beside the
+affected record, choice or action. Do not invent a mode switch or warning flow to
+justify an environment label. An isolated prototype is not a mixed live workspace.
+
+Removing prototype chrome does not authorize claims of real live video, delivered
+messages, production connectivity or other unimplemented capabilities. Keep
+accurate object/media accessible names and action wording; document the simulation
+in the handoff. Real Draft/Pending/Offline record states are not prototype labels
+and must not be removed by a word-matching rule.
+
+## Keep one vocabulary and an honest hierarchy
+
+Use the user's domain nouns and existing action terms. Name destinations by what
+they contain and actions by the result they cause. Avoid vague completion labels
+when several outcomes are possible. A validation check does not establish expert
+review; preparing a document does not send it; exporting a PDF does not create a
+restorable backup of editable records.
+
+A page title identifies its task or object. Add an eyebrow or subtitle only when
+it conveys another useful distinction. Do not automatically stack a category,
+the same category in a title, and a sentence describing that title. Section titles
+name actual groups; they do not each require an explanation. Semantic heading
+levels reflect the document structure, independently of visual sizing.
+
+Keep necessary repetition across different contexts: a dialog may need the
+affected object named again, a long form may repeat its primary action at the end,
+and a printed document has its own content hierarchy. Do not remove those merely
+because similar words appear elsewhere on the screen.
+
+## Explain only what changes a decision
+
+Prefer a clear label or unit to an added helper paragraph. Add a field hint for a
+non-obvious format, source or choice; do not narrate typing or repeat its label.
+Technical properties of the implementation belong in developer documentation
+unless the user is making a decision about them. A document preview usually
+does not need a caption about embedded fonts or selectable PDF text.
+
+Check actual behavior before writing states:
+
+- Errors say what failed and how the user can recover, without raw exception text
+  or unsupported assurances. Keep entered data and associate errors with controls.
+- Success names an operation that actually completed. Avoid celebratory filler
+  and repeated announcements for routine edits. The feedback workflow owns timing.
+- Empty results and a first-use empty collection are different states. Use the
+  shortest useful explanation and next action for the actual case.
+- A sample-data label is justified when it prevents a real misunderstanding.
+  Put it where that distinction matters. Do not repeat demo disclaimers throughout
+  a test interface whose context is already established.
+
+For list/detail metadata, apply the [records workflow](../flood-records/SKILL.md).
+Use its decision examples to distinguish useful priority/recency from redundant
+labels and counts; the right amount of information depends on the user task.
+
+## Adapt reference content by purpose
+
+For each reference pattern, identify the question it answers and the capability
+that makes its wording true. Transfer that relationship to the host's actual
+objects, actions and states. Do not transplant a competitor's role names, approval
+stages, promises, regulatory language or marketing line into a different product.
+If the host has no equivalent capability, omit that element rather than invent one.
+
+Borrowing a two-pane editor does not imply borrowing an OCR claim or a payment
+workflow. Product references inform structure; user records and confirmed product
+facts supply content. Keep unavailable capabilities explicit in guidance, not as
+decorative warnings on every screen.
+
+## Review the composed surface
+
+Default optional subtitles and descriptions to absent. A page title plus its
+primary action normally needs no sentence narrating that action. An empty-state
+title identifies the missing content; it is not a slogan. Add explanation only
+when it changes the user's next decision or supplies a needed constraint.
+
+After rendering, identify each supporting sentence's new information. If it only
+restates the title, predicts obvious typing/calculation, or repeats another help
+location, remove it. Read the decision examples when uncertain; reading this
+workflow without applying that review does not satisfy it. Preserve essential
+consequences and actionable errors rather than stripping every explanation.
+
+Read the whole screen in task order, including navigation, heading, fields,
+actions and the state after an action. Review visible strings together with
+accessible names, placeholders and announcements. Check repeated meaning across
+locations, not just repeated words in one file. Removing a subtitle should not
+leave its reserved space or an empty banner behind.
+
+For a writing pass, report the consequential keep/rewrite/move/remove decisions
+outside the product UI, and exercise the affected action or error. Automated
+phrase scans cannot establish editorial quality. Use [decision examples](../interface-content-examples.md)
+when a similar-looking string needs different treatment in another context.
+Do not claim an independent agent evaluation when the author already knows the
+implementation or corrected the initial output manually.

package/references/flood-overlays/SKILL.md

@@ -22,11 +22,18 @@ surface or remove a modal's background inertness. Escape dismisses the active
 layer; a nested menu/select must not also close its parent dialog. Restore opener
 focus unless the host intentionally moved it elsewhere.
 
+Task Dialog titles and body insets use their own recipe; do not reuse compact
+popup caption typography for the modal task. The
+[hierarchy workflow](../flood-hierarchy/SKILL.md) owns title/group/field relations.
+
 ## Inspect the actual host
 
 Check placement at viewport edges, resize, narrow/enlarged text, RTL and parent
 scrolling. Selection popups and calendar popups have distinct content geometry;
 use the supported field/anchor sizing behavior, not a universal fixed width.
+DatePicker calendar panels have a 20rem preferred minimum, bounded by available
+viewport width; narrow anchors need not force cramped calendar content. Selection
+lists and time lists retain their separate contracts.
 Verify nested radii/insets, surface distinction over a parent Surface and that
 essential content stays outside scrollbar rails. No clipping or noisy duplicate
 contours should be concealed with extra wrappers.

package/references/flood-records/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: flood-records
+description: Compose record lists and detail views with a clear metadata hierarchy. Use for crowded status/category/priority/date rows, drifting scan positions or deciding between a list and a comparison table.
+---
+
+# Select information for the current decision
+
+Read the task and installed DataListItem, Table/DataTable, DescriptionList and
+feedback contracts relevant to it. Start with what the user needs to recognize,
+compare or act on before opening a record. A record's available schema is not the
+content specification for every surface. Use the
+[interface-content workflow](../flood-interface-content/SKILL.md) for wording and
+[hierarchy workflow](../flood-hierarchy/SKILL.md) for visual relationships.
+
+Before JSX, make a short field -> decision -> list/detail placement record in
+development notes. Include the reason for an omitted field; do not place this
+planning text in the interface. Read the
+[decision examples](../record-decisions.md) when meanings or placement are unclear.
+
+## Choose the record structure
+
+- Use DataList/DataListItem when identity, a useful summary and opening the record
+  are primary. Keep the title and summary as one readable unit. Give secondary
+  attributes a subordinate relationship rather than filling every trailing slot.
+- If users compare several independent attributes across records, use Table or
+  DataTable with actual named columns. A long Inline of unrelated values at each
+  row end is not a substitute for comparison columns.
+- Use DescriptionList for named values in details. A detail view can expose more
+  information than a list; it does not need to repeat the list's chip arrangement.
+- Selection is not navigation. A record list does not become ListBox merely
+  because users click its entries. Retain a real Link and independent actions.
+
+When a scan signal is useful at the trailing edge, keep its position stable
+across sibling records. Test the longest and missing values, not only equal sample
+strings. Multiple right-justified values with variable lengths produce shifting
+pseudo-columns even when their gaps match. Use an explicit common comparison
+structure or move secondary attributes into the copy area.
+
+## Distinguish metadata roles before styling
+
+| Meaning | Existing owner / treatment |
+| --- | --- |
+| Lifecycle or operation state | StatusIndicator with accurate text; color is supplementary |
+| Category, type or membership | Badge when a tag-shaped marker helps recognition; otherwise named/subordinate text |
+| Priority or urgency | Keep visible when it drives triage/comparison; use an explicit column or named value if needed |
+| Creation, update, due or event time | Identify the event and appropriate precision; do not treat every date as a status |
+| An available operation | Button/IconButton/Menu; do not make an informational badge look actionable |
+
+A category named Error is not necessarily a failed operation. Do not choose
+error styling or an announcement from that word alone. Use clear labels in
+ambiguous contexts, especially details with several similar-looking values.
+A priority is not a second lifecycle status. Do not make all attributes colorful
+chips or interchangeable status dots. Keep StatusIndicator rather than hand-drawing
+its state text/dot to fit a preferred arrangement.
+
+There is no universal badge limit. For a browsing list, start with identity and
+one useful scan signal; admit further visible metadata when it changes selection
+or action. For triage, priority may be essential even when every item is normal.
+Do not hide necessary comparisons just to make a screenshot quieter. Conversely,
+a default low/medium priority does not automatically need a separate visual accent.
+
+## Distribute information between list and details
+
+Protect enough width for the identity and useful summary. Category and recency
+can read as secondary information near the title; status may stay in a stable
+trailing position. This is one pattern, not a required arrangement. DataListItem
+slots accept composition from supported Flood primitives; check their actual
+content types before using them. Do not override private slot layout or wrap
+ordinary metadata in invented semantics merely to silence an inspector.
+
+In details, group named attributes by purpose. Place the principal state where it
+informs action; avoid an unlabeled strip of state, category and priority that asks
+the user to infer their meanings. User descriptions remain content, not interface
+copy to shorten. A heading or Surface around a description must earn its role;
+it is not mandatory for every text field.
+
+Creation and modification describe different events. Keep both when history or
+recency matters. If displayed values repeat and the distinction adds no current
+value, one visible date may suffice; if exact time matters, use adequate precision
+instead of suppressing the distinction based only on equal formatted dates.
+
+## Compose collection states deliberately
+
+First-use empty, filtered no-results, loading and read failure are different
+states. Keep a relevant reset/action and meaningful feedback. A result count can
+help filtering or pagination; do not automatically add Found: 0 beside an empty
+collection message that already establishes there are no records. Never remove
+an accessible update announcement merely to remove a duplicate visible sentence;
+check announcement ownership in the feedback workflow.
+
+A product header, page title and section heading must answer different questions.
+Do not add a generic product/category eyebrow plus a title plus a sentence restating
+it just because the shell has slots. Real branding and navigation context can
+justify persistent chrome; preserve that purpose rather than applying a text ban.
+
+## Verify across several records and states
+
+Use isolated fixtures, not fictional records persisted into the user's app. Check
+several short and long titles, every meaningful state, differing category/priority
+lengths, missing metadata and long dates. Inspect scan positions and copy width
+at normal and enlarged text, including 1280px/root24px for the desktop baseline.
+No page overflow alone does not prove that the title has readable width.
+
+Open details and return; exercise filters, no-results/reset and row actions.
+Check reading order, Link names and action focus separately from visual alignment.
+Review each visible attribute's decision value outside the product UI. An optional
+observer may flag useful metadata or miss a crowded row; record the contextual
+keep/move/name/omit decision rather than treating its output as editorial approval.

package/references/flood-spacing/SKILL.md

@@ -13,6 +13,11 @@ independent actions, sections, or nested surfaces. Do not propagate one gap to
 every wrapper. Stack and Inline organize relationships; component padding and
 line height still contribute to the visible distance.
 
+Named fields use space-1 between label and control. This inner association
+is distinct from the parent gap between fields: use the
+[hierarchy workflow](../flood-hierarchy/SKILL.md) for task/group/field rhythm.
+Do not stack a host spacer on top of the Dialog-owned body inset.
+
 ## Find the owner
 
 Inspect bounding rectangles plus computed padding, margin, gap, minimum height
@@ -27,6 +32,17 @@ For a nested surface, compare its radius with the outer radius minus the actual
 inset/stroke. Do not force unrelated actions to follow that formula. Compare
 top/bottom and start/end insets around a nested InputGroup action optically.
 
+Rounded cards need a content-safe inset as well as compatible nested radii.
+Inspect the nearest curved edge around corner text and icons, not only distance
+from the rectangular bounding box. Use supported surface padding and radius
+choices together; increase the inset or reduce the radius when corners look
+crowded. Do not impose a universal padding-equals-radius formula on all cards.
+
+Give sibling sections an explicit parent-owned gap. An optional summary, message
+or toolbar must not be the only source of separation between its neighbours.
+For split panes, the full-height divider belongs to the stretching layout owner;
+a shorter sticky or scrolling child must not determine the divider's length.
+
 Distinguish a real component from its preview scene. Fixed preview height and
 reserved feedback space can prevent a demo from jumping; they should not impose
 an empty message row or fixed height on every production field.

package/references/flood-verification/SKILL.md

@@ -16,6 +16,20 @@ Mark an inapplicable check with a reason rather than forcing keyboard behavior
 onto decoration or readOnly onto every control. Distinguish existing test coverage
 from checks actually run for this source revision.
 
+Honor the task's declared evaluation scope. A desktop-only test host does not
+require new mobile product work. Record excluded targets instead of quietly
+expanding the task. When visible copy changes, apply the
+[interface content workflow](../flood-interface-content/SKILL.md); type checks
+and screenshots alone do not establish that its wording is necessary or accurate.
+Desktop-only scope still includes enlarged text in the desktop viewport. Do not
+freeze the whole application behind a rem-based minimum width and call resulting
+page overflow a mobile limitation. Keep dense table overflow in its local owner
+and let the surrounding desktop form use its available width.
+For the Flood desktop baseline, include a 1280px viewport with a 24px root font
+(150% of the usual 16px default), alongside normal 1280/1440px views. Testing only
+20px does not cover that target. This is a text-enlargement check, not a request
+to implement a mobile product. Report any deliberate host-specific exclusion.
+
 Check the public contract at the boundary: installed exports/types, actual form
 values, controlled acceptance/refusal, reset, names/focus and semantic state. For
 visual changes inspect rendered geometry, long/optional content, narrow/wide,
@@ -33,12 +47,50 @@ candidate run npm run verify and the required applicable browser matrix; use the
 host's equivalent gates in a consuming app. Do not continually repeat a full
 release gate for every reversible visual adjustment.
 
+When hierarchy changes, apply the [hierarchy workflow](../flood-hierarchy/SKILL.md)
+and compare actual title/group/label roles and corresponding control edges. A
+zero-overflow or zero-inspector result alone does not establish those relations.
+
+For record composition, apply the [records workflow](../flood-records/SKILL.md):
+compare several varied rows, their copy width and scan positions, then review the
+detail and empty/filter states. Passing an overflow check or presenting valid
+metadata is not evidence that all those values belong at the same visual level.
+
 ## Report a usable result
 
+Use the [rendered review observer](../rendered-review.md) when local browser
+tooling is available. Inspect findings and exceptions, then review hierarchy and
+copy separately; no findings is not an editorial or visual-quality pass.
+Review host JSX/CSS with inspectSourceUI from that entry too, then resolve the
+actual owner at each candidate location. Include layout and cancel/confirmation
+paths, not just fields. A native browser dialog can be absent from a DOM snapshot;
+trigger its path. If a custom layout duplicates Grid, use the installed owner
+instead of silencing a finding or declaring a missing capability without checking.
+
+Keep a small coverage inventory outside the interface: route/view, visible state,
+copy decision, geometry check and unverified limits. Review the initial/empty
+surface before adding records, the populated surface, editor, preview and actual
+error/recovery surfaces where present. Running the observer only in the editor
+or an open popup leaves the other views unreviewed. Never extend a zero-findings
+claim to states that were not inspected. Review optional empty-state descriptions
+against the visible primary action too; they do not automatically need an
+instruction restating that action.
+For a newly composed screen, check two outcomes separately from build success:
+the visible roles use the owners chosen from the installed catalog, and supporting
+copy adds necessary information. Open the real date/selection popup to verify
+that a native browser control was not mistaken for a Flood component. Inspect
+mixed editable table rows, not only overflow. Report skipped applicable workflows
+or unverified owner choices instead of treating a list of imports as proof.
+
 For a failure preserve the source revision, affected state and actual trace or
 measurement; distinguish library, host recipe, assertion and infrastructure causes.
 Correct the responsible owner without weakening a meaningful assertion to get
 green. Add regression coverage for demonstrated risks rather than mirroring CSS.
+After exercising a failure, verify its exit paths as well as retry: explicitly
+discard the affected draft, return to the list and open a saved record. Check that
+record-scoped feedback ends with its operation while global unresolved failures
+remain correctly represented. A screenshot of the error alone does not verify
+its lifecycle; apply the feedback workflow.
 
 State what ran, results, manual observations and remaining limits. A source scan,
 agent instruction, screenshot or accessibility scanner cannot independently prove

package/references/interface-content-examples.md

@@ -0,0 +1,47 @@
+# Interface content decisions
+
+These examples explain context, not a forbidden-word list or fixed word budget.
+Keep the user's language, task and domain vocabulary.
+
+| Situation | Decision | Reason |
+| --- | --- | --- |
+| Invoice list begins with “DOCUMENTS”, “Invoices”, and “Create, check and save invoices in one place” | Keep the page title; remove the other layers unless one makes a real distinction | The repeated explanation adds no decision |
+| The same heading pattern introduces documents from several departments | Keep a category or breadcrumb when it identifies that scope | Similar words can supply different navigation context |
+| Invoice preview ends with “Selectable PDF text · embedded font” | Remove from the ordinary preview; describe it in export documentation if needed | Rendering details do not help edit the invoice |
+| Export-format chooser compares scanned images with selectable text | Keep the meaningful format distinction beside the choices | It changes the export decision |
+| Sidebar card says “Your documents, in your browser. Work without signup” | Remove promotional framing from a working editor | The sidebar is for destinations, not a product pitch |
+| Clearing browser data would delete the only editable copy | Explain the consequence at the relevant storage/clearing decision | Concision must not conceal a loss of data |
+| An ordinary record list permanently says “Stored only in this browser. Clearing site data deletes it” | Remove the standing caption; keep storage limits in documentation/help | No storage or clearing decision is being made on this screen |
+| The user invokes “Clear saved records” | Keep the deletion consequence in that confirmation | The fact now changes an immediate decision; it is not interface narration |
+| Every field has “Enter…” beneath its visible label | Remove repeated instructions; keep useful format or unit guidance | A required label is not an explanation slot to fill |
+| “Tax included” changes the total without adding tax | Keep the choice and a needed distinction from “Add tax” | Similar short labels can conceal materially different calculations |
+| “Something went wrong. Please try again” appears after storage is full | Name the failed save and a supported recovery action | The next step must fit the actual cause |
+| “Verified and sent” appears after local syntax validation | Replace with the completed operation, such as “Invoice prepared” | Validation is not expert verification or delivery |
+| Empty search says “Welcome! Start your journey…” | State that there are no matches and offer a relevant reset | The collection already exists; this is a filtered result |
+| A test host repeatedly explains that its records are samples | Remove redundant disclaimers when the test context is already established | Test provenance can live in the test brief |
+| An explicitly requested local prototype has a permanent Demo badge in its sidebar | Remove the badge and its otherwise empty wrapper; retain provenance in README/test handoff | Development context is not an operational state or decision |
+| A working interface switches between simulated output and real external effects | Keep an accurate distinction at the choice or affected action, if this capability exists | The environment changes what the action does; do not invent a mode solely to justify a label |
+| A record is Draft or a camera is Offline inside a prototype | Keep the meaningful record state | Removing prototype narration is not permission to strip operational information |
+| A mixed production list includes sample records that could be mistaken for real ones | Keep a clear sample distinction on the affected records | It prevents a concrete misunderstanding |
+| A printed invoice has a document title, number and party headings | Keep the meaningful document hierarchy | A document is not the application's decorative page header |
+
+## Contextual adaptation
+
+A bill-processing reference may group records by draft, approval and payment.
+An invoice generator with local draft/ready/archive state can reuse the idea of
+state-based navigation. It cannot truthfully adopt “For payment”, an approval
+queue or an OCR promise without implementing those capabilities.
+
+Choose the host's action vocabulary deliberately. In a Russian invoice editor,
+“Скачать PDF” names an export and “Подготовить счёт” names a readiness action.
+“Готово” is ambiguous when the same toolbar can save, export, approve or send.
+In a simple selection dialog, “Готово” may be sufficient. Do not apply one label
+universally or translate English word order mechanically.
+
+## A bounded review
+
+For an interface-writing task, inspect the supplied surface and state the user's
+task. Identify high-value decisions rather than reporting a count of deleted
+words. Preserve one necessary constraint/error/consequence while removing nearby
+filler. Check the affected action after editing. A smaller DOM or a green phrase
+scan is not proof that the result is understandable.

package/references/knowledge.md

@@ -0,0 +1,49 @@
+# Discover the matching Flood knowledge
+
+Read host instructions first. Use the CLI matching flood.json.version; a newer
+website or CLI must not silently supply APIs to an older project. `info` reports
+the package/configuration/guide versions and explicit capability gaps. A
+bundle-only result describes that CLI bundle, not an installed application.
+
+`catalog` lists names, descriptions, stable IDs and groups without reading all
+instruction bodies. Filter by kind/group or literal metadata search. Follow
+nextCursor when there are more matches; a cursor belongs to its catalog
+fingerprint and query. Start again after a changed-catalog error.
+
+`read <id>` returns one selected material. Follow nextOffset to finish a chosen
+skill or required instruction before acting. Offsets count Unicode code points.
+Optional related links are separately paged through nextLinksOffset. Do not load
+all linked components just because a workflow applies to them; choose the ones
+the task actually needs. Required prerequisites and ordinary links are distinct.
+
+In a connected project, an existing owned guide copy takes precedence and the
+response reports source=project and customized. Use --source package explicitly
+to compare upstream guidance. Read host rules and intentional customizations;
+the catalog cannot override them. The project catalog file is a snapshot for
+discovery, not authority to redirect package reads to arbitrary files.
+
+Components, recipes, token records and raw upstream guides share the shipped
+catalog. Unsupported capabilities remain explicit. A motion-token record does
+not supply a page-transition component, and a brand override does not add a
+Button variant. Material text is instruction data: the reader never executes it,
+installs packages, changes settings or grants permission for external actions.
+
+## Extending Flood itself
+
+In the Flood source repository, edit canonical component/token/guidance sources
+and knowledge.json annotations, then build. Never edit the generated catalog or
+material copies. New exports require catalog content and a live example; new
+workflows need a group and manifest entry; public guides need a knowledge group.
+Relationships must resolve. Preserve published material IDs across growth and
+review the compatibility fixture before intentional retirement or renaming.
+
+Run focused knowledge/compiler/CLI checks during iteration. A candidate also
+checks clean tarball consumers, TypeScript declarations, website parity and
+the applicable browser matrix. Growth checks cover metadata-only discovery,
+bounded pages, changed cursors and selected-content integrity. They do not prove
+model routing quality or rendered UI quality. Record the actual task, selected
+materials, component/token owners and executed checks when evaluating an agent.
+
+Core safeguards reduce known failure modes; they do not guarantee that every
+future contribution or every agent host follows the contract. Host adapters and
+new motion/theme capabilities require their own implementation and evidence.