@flood-md/agent 0.2.9 → 0.2.11

package/dist/materials/component-toggle-group.md

@@ -0,0 +1,44 @@
+# ToggleGroup
+
+Optional single or multiple selections exposed as pressed buttons.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, ToggleGroup } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ToggleGroup label="Text formatting" defaultValue={["bold"]} options={[{value: "bold", label: "Bold"}, {value: "italic", label: "Italic"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Tab reaches each enabled action. Arrows/Home/End move focus without selecting. Single selection can be cleared.
+- Use RadioGroup for form choices and tabs for switching panels. ToggleGroup does not submit form values.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `options` | `readonly ToggleOption[]` | `Required` |
+| `selectionMode` | `"single" \| "multiple"` | `"multiple"` |
+| `value` | `readonly string[]` | `—` |
+| `defaultValue` | `readonly string[]` | `[]` |
+| `onValueChange` | `(value: string[]) => void` | `—` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
+| `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"subtle"` |
+| `disabled` | `boolean` | `false` |
+| `iconOnly` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "role" \| "children" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-toggle.md

@@ -0,0 +1,40 @@
+# Toggle
+
+A native button with a persistent pressed state.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Toggle } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Toggle defaultPressed>Bold</Toggle>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Keep the accessible name stable; Enter/Space toggle pressed. Supports controlled pressed/onPressedChange or defaultPressed.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"subtle"` |
+| `tone` | `"default" \| "danger"` | `—` |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
+| `loading` | `boolean` | `—` |
+| `pressed` | `boolean` | `—` |
+| `defaultPressed` | `boolean` | `false` |
+| `onPressedChange` | `(pressed: boolean) => void` | `—` |
+| `iconOnly` | `boolean` | `false` |
+| `Native HTML props` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-pressed" \| "type" \| "role" \| "defaultValue">` | `Forwarded` |

package/dist/materials/component-toolbar.md

@@ -0,0 +1,46 @@
+# Toolbar
+
+A compact action panel with one Tab entry and directional keyboard navigation.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Toolbar, Button, Toggle } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Toolbar label="Editor actions">
+        <Button variant="ghost">Undo</Button>
+        <Toggle variant="ghost">Bold</Toggle>
+        <Button variant="ghost">Share</Button>
+      </Toolbar>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use Button, IconButton, Toggle, native buttons/links and Menu triggers. Keep inputs, Select, Tabs and ToggleGroup outside this action-only toolbar.
+- Arrows move focus without activation; Home/End jump to the ends. Disabled and hidden actions are skipped. One Tab entry is established after hydration; before JavaScript native child tab order remains.
+- Horizontal arrows follow writing direction. Vertical arrows move between actions; open a vertical toolbar Menu with Enter/Space. Horizontal menus retain ArrowUp/Down opening.
+- loop defaults to true. Native div props/ref target the toolbar; preserve a meaningful label. Available in 0.2.4.
+- shape defaults to rounded; pill uses the action radius and a horizontal single scrollable rail.
+- variant="plain" removes the material and outer inset for grouping peer controls; contained remains the default. Keyboard ownership is unchanged.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `loop` | `boolean` | `true` |
+| `shape` | `"rounded" \| "pill"` | `—` |
+| `variant` | `"contained" \| "plain"` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | `Forwarded` |

package/dist/materials/component-tooltip.md

@@ -0,0 +1,40 @@
+# Tooltip
+
+Brief text help on hover or focus, with collision-aware placement.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Tooltip, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Tooltip content="Additional context" trigger={trigger => <Button {...trigger}>Hover or focus</Button>} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Requires native Popover API.
+- Forward trigger props and ref to one actual button. Tooltip is text-only; interactive content belongs in Popover.
+- Escape dismisses. Hover can move onto the tooltip; focus stays on the trigger. Do not use it as the only accessible name or essential instruction.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `content` | `string` | `Required` |
+| `trigger` | `(props: TooltipTriggerProps) => ReactNode` | `Required` |
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` |
+| `align` | `"start" \| "center" \| "end"` | `"center"` |
+| `delay` | `number` | `300` |
+| `disabled` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "content" \| "title" \| "role">` | `Forwarded` |

package/dist/materials/component-tree-select.md

@@ -0,0 +1,56 @@
+# TreeSelect
+
+Single selection from a hierarchical collection inside a popup.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, TreeSelect } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <TreeSelect label="Destination" name="destination" items={[{value:"design",label:"Design",selectable:false,children:[{value:"foundations",label:"Foundations"},{value:"components",label:"Components"}]}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- This first version selects one item; Tree provides standalone multiple selection.
+- Values are globally unique and expansion remains independent of selection.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `items` | `readonly TreeItem[]` | `Required` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `placeholder` | `string` | `—` |
+| `name` | `string` | `—` |
+| `form` | `string` | `—` |
+| `required` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `invalid` | `boolean` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `—` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `expandedValues` | `readonly string[]` | `—` |
+| `defaultExpandedValues` | `readonly string[]` | `—` |
+| `onExpandedValuesChange` | `(values: string[]) => void` | `—` |
+| `emptyMessage` | `string` | `—` |
+| `invalidSelectionMessage` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onChange" \| "defaultValue">` | `Forwarded` |

package/dist/materials/component-tree.md

@@ -0,0 +1,52 @@
+# Tree
+
+A selectable application hierarchy with independent expansion and keyboard focus.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Tree } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Tree label="Project files" items={[{value:"source",label:"Source",children:[{value:"button",label:"Button.tsx"}]}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Tree uses tree/treeitem/group semantics, logical arrows, Home/End and typeahead. Moving focus does not select an item. Enter/Space explicitly selects; multiple selection does not cascade.
+- Items have globally unique values. Expansion uses expandedValues/defaultExpandedValues/onExpandedValuesChange; selection uses value/defaultValue/onValueChange. Controlled refusal preserves the host state.
+- Read-only allows browsing without selecting. Disabled items remain discoverable but cannot select or expand. hasChildren/loading represent host-owned deferred branches; no fetching or virtualization is built in.
+- Application selection writes no form values. Use NavigationTree for ordinary native links. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `items` | `readonly TreeItem[]` | `Required` |
+| `value` | `string \| readonly string[]` | `—` |
+| `defaultValue` | `string \| readonly string[]` | `—` |
+| `onValueChange` | `(value: string \| string[]) => void` | `—` |
+| `multiple` | `boolean` | `—` |
+| `expandedValues` | `readonly string[]` | `—` |
+| `defaultExpandedValues` | `readonly string[]` | `—` |
+| `onExpandedValuesChange` | `(values: string[]) => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `emptyMessage` | `string` | `—` |
+| `loadingMessage` | `string` | `—` |
+| `unloadedMessage` | `string` | `—` |
+| `readOnlyMessage` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onSelect" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-upload-item.md

@@ -0,0 +1,52 @@
+# UploadItem
+
+A host-controlled upload row with explicit progress and applicable actions.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, UploadList, UploadItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <UploadList label="Uploads">
+        <UploadItem name="Brand guidelines.pdf" size={2400000} state="uploading" progress={45} />
+      </UploadList>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Queued/uploading can expose cancel; error/cancelled can expose retry; settled rows can expose remove.
+- Unknown progress is indeterminate. StatusIndicator and Progress remain distinct reused primitives; their row can wrap when the list container is constrained. No network or upload queue is built in.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `name` | `string` | `Required` |
+| `size` | `number` | `—` |
+| `mimeType` | `string` | `—` |
+| `format` | `string \| null` | `—` |
+| `thumbnail` | `ReactNode` | `—` |
+| `href` | `string` | `—` |
+| `download` | `boolean` | `—` |
+| `onPreview` | `() => void` | `—` |
+| `onRemove` | `() => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `labels` | `FileActionLabels` | `—` |
+| `formatSize` | `(bytes: number) => string` | `—` |
+| `state` | `"queued" \| "uploading" \| "success" \| "error" \| "cancelled"` | `Required` |
+| `progress` | `number` | `—` |
+| `error` | `string` | `—` |
+| `onCancel` | `() => void` | `—` |
+| `onRetry` | `() => void` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLLIElement>, "children" \| "title">, "description">` | `Forwarded` |

package/dist/materials/component-upload-list.md

@@ -0,0 +1,40 @@
+# UploadList
+
+A named native list of host-controlled upload rows.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, UploadList, UploadItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <UploadList label="Uploads">
+        <UploadItem name="Brand guidelines.pdf" state="uploading" progress={45} />
+        <UploadItem name="Logo.svg" state="success" />
+        <UploadItem name="Cover.png" state="error" error="Connection interrupted" />
+      </UploadList>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Each row has its own state and stable host identity.
+- Cancellation, retry and removal callbacks are intents for the application.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `density` | `"compact" \| "comfortable"` | `—` |
+| `dividers` | `boolean` | `—` |
+| `label` | `string` | `Required` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLUListElement>, "role">` | `Forwarded` |

package/dist/materials/component-visually-hidden.md

@@ -0,0 +1,37 @@
+# VisuallyHidden
+
+Nonvisual content with optional reveal when keyboard focus enters.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Text, VisuallyHidden } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Text>Project updated.</Text><VisuallyHidden>Changes save automatically.</VisuallyHidden>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Content remains in the accessibility tree. Default is for noninteractive text only.
+- Use focusable for a skip link or another focusable descendant: the wrapper becomes visible while it contains focus. Supply visible focus styling on the actual control.
+- This is not aria-hidden, display:none or a conditional unmount. as accepts span/div.
+- Available in 0.2.4; use matching installed declarations.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `as` | `"span" \| "div"` | `"span"` |
+| `focusable` | `boolean` | `false` |
+| `Native HTML props` | `HTMLAttributes<HTMLElement>` | `Forwarded` |

package/dist/materials/guide-agent-knowledge.md

@@ -0,0 +1,95 @@
+# Agent knowledge
+
+Flood 0.2.11 includes 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
+
+```sh
+npx @flood-md/cli@0.2.11 info --json
+npx @flood-md/cli@0.2.11 catalog --kind workflow --group foundations
+npx @flood-md/cli@0.2.11 catalog --kind component --search table
+npx @flood-md/cli@0.2.11 read recipe:table-bulk-actions
+npx @flood-md/cli@0.2.11 read component:data-table
+```
+
+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.
+
+For a screen that filters one table between two views, start with
+`read component:segmented-control` and follow its link to `workflow:records`.
+If the screen switches between independent panels, read `component:tabs`.
+Before delivery, open the list and a selected record together, then use
+`workflow:interface-content` and `reference:interface-content-examples` to
+decide which labels, counts and status messages the user needs in each view.
+
+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.

package/dist/materials/guide-agents.md

@@ -0,0 +1,103 @@
+# Using Flood with an agent
+
+Start with the host's instructions, package.json, flood.json and installed
+flood/DESIGN.md. Use matching package/CLI versions and declarations. A newer
+website example does not add APIs to an older installation.
+
+Version 0.2.3 includes the expanded skill, rules and reference bundle, including
+spacing guidance. Existing projects keep their installed files; compare new
+guidance before updating customized instructions.
+
+Version 0.2.9 adds ten specialized routed skills for stabilizing and
+composing the dark base. See [Skills](skills.md) for their applicability and full
+sources. The website index is generated from the same bundle metadata rather
+than a second handwritten skill catalog. Source additions do not update an
+already installed package; use the guide set matching your installation.
+
+Version 0.2.11 adds [versioned knowledge discovery](agent-knowledge.md):
+info reports installation context, catalog discovers compact metadata, and read
+loads a selected contract or workflow. The catalog includes typed recipes and
+semantic token records. Unknown capabilities and version mismatches are explicit;
+copied host guides remain project-owned.
+
+For discovery, give an agent [flood.md/llms.txt](https://flood.md/llms.txt).
+It identifies deployed status and entry points. Follow [installation](installation.md);
+preview the matching CLI's init with --dry-run before applying it within the user's
+scope. The CLI does not install an agent runtime or require a hosted Flood service.
+
+## Compose from primitives
+
+Flood includes the [Flood composition skill](../packages/agent/references/flood-composition/SKILL.md).
+The main Flood skill routes component, website and playground work to it. The
+manifest installs the full skill under
+`.agents/skills/flood-ui/references/flood-composition/SKILL.md`; it is loaded by
+that router rather than relying on independent discovery of nested skills.
+Existing installations must compare and merge new guidance deliberately.
+
+Reuse the existing library component; fix the relationship in its proper owner.
+If a reusable primitive is missing, build or extend it before the composition.
+Do not replace StatusIndicator with custom text, hide its anatomy, or duplicate
+a Badge/Progress/Dialog implementation just to make one layout fit.
+
+## Files and responsibilities
+
+For reusable components, the composition skill also routes to
+[component families](../packages/agent/references/component-families.md): choose
+the closest existing anatomy and compare sizing, shape, nested insets and states
+in the same scene. Flood's repository instructions require that same guide for
+its own authors. Installed projects receive it through the matching manifest and
+knowledge catalog; existing customized guides are not silently overwritten.
+
+| Project file | For whom / when | Prerequisite | Source of truth | What to check |
+| --- | --- | --- | --- | --- |
+| flood.json | Developer / agent, setup or upgrade | Existing React project | Exact installed release, framework and paths | Matching CLI doctor |
+| flood/DESIGN.md | Designer / developer / agent, every composition | Installed declarations | Version-matched UI contracts | Supported props and rendered states |
+| .agents/skills/flood-ui/SKILL.md | Skill-aware client, Flood UI work | Project context | Short task router | Load only the relevant reference |
+| references/routing.md in the skill folder | Human / agent, resolve ownership | Matching guide set | Responsibility and source matrix | Correct source and prerequisites |
+| references/composition.md in the skill folder | Screen/form author | User content and installed APIs | Composition workflow | Intrinsic actions, responsive forms, close choice labels |
+| references/spacing.md in the skill folder | Designer / developer / agent | Installed tokens and rendered host | Spacing and density decisions | Visible gaps, row pitch, wrapping and nonoverlapping touch targets |
+| references/accessibility.md in the skill folder | Control author / reviewer | Runnable host | Interaction and perception | Names, keyboard, focus, forms and contrast context |
+| references/customization.md in the skill folder | Theme author | Installed token manifest | Semantic override workflow | Resolved roles and affected states/surfaces |
+| references/verification.md in the skill folder | Developer / reviewer, completion | Host checks | Evidence requirements | Commands, manual results and gaps |
+| flood/rules.json | Human / agent / project tooling | Same bundle | Rule IDs, conditions, sources and checks | Evidence for each applicable rule |
+| flood/manifest.json | Installer / reviewer | Matching package | Explicit source → project-path mapping | Complete files; existing files preserved |
+| workflows.json in the skill folder | Agent / reviewer, task selection | Same installed bundle | Workflow applicability | Read relevant skills; applicability is not behavioral proof |
+
+Manifest `entry` and rule `guide` paths are package-source paths. Resolve them
+through `manifest.files`: each source maps to a target relative to the host
+project root. `installedEntry` names the installed skill directly. Manifest
+version and DESIGN header are checked by doctor alongside package alignment;
+customized guide contents are preserved and must be merged deliberately.
+
+The package publishes DESIGN.md, SKILL.md, rules.json, manifest.json and
+references/*.md. The website exposes the same sources under /agent/.
+The [routing reference](../packages/agent/references/routing.md) connects each
+question with its governing source and verification method.
+
+## Use only the context needed
+
+For a settings form, read DESIGN.md and SKILL.md, then composition/accessibility.
+Consult installed declarations for actual Field/Select props and read only those
+component pages. Before completion use verification. For a color-only change,
+load customization and the relevant token roles; unrelated guides stay unloaded.
+
+Clients supporting the skill-folder convention can discover it. Others can read
+it explicitly or link it from existing instructions. The installer preserves
+AGENTS.md; it does not configure clients or guarantee automatic discovery.
+
+The rules index is data, not an executable policy engine. It cannot make an agent
+obey guidance or certify accessibility. Host checks and Flood's repository
+verification supply evidence. Doctor checks package alignment and expected regular
+files; it does not parse CSS imports or assess visual quality/completed user flows.
+
+## Safe installation and upgrades
+
+Init refuses existing owned files and linked destinations before npm runs, then
+rechecks after installation. During upgrades compare new package sources with
+installed copies, merge deliberately and retain host requirements. Do not delete
+customized guides merely to make init succeed.
+
+Import @flood-md/react/styles.css once and compose new dark interfaces in
+FloodRoot. See [layout](layout.md), [components](components.md) and
+[customization](theming.md). Flood guidance governs UI use; it grants no authority
+to publish, delete data, transmit source or bypass the user's instructions.