@flood-md/agent 0.2.9 → 0.2.11

package/dist/materials/guide-faq.md

@@ -0,0 +1,84 @@
+# Frequently asked questions
+
+## Does Flood use shadcn, Radix, Base UI or Tailwind?
+
+No. Flood's controls, CSS tokens and CLI are authored in this repository. React
+and browser-native form elements provide the underlying platform APIs.
+
+## Does it support Next.js?
+
+Yes. Import the global stylesheet in app/layout.tsx. Flood's React entry preserves
+its use-client boundary. Compose callbacks, state and Field's function child in
+your own client component. The integration fixture tests React 19 and Next.js App
+Router. Clean-package checks also exercise React 18.3 and 19 server rendering;
+the full interactive Next.js fixture uses React 19.
+
+## Is this the same installation model as shadcn?
+
+Flood currently installs versioned npm dependencies. It does not copy editable
+component source into your application or provide a source-file merge engine.
+Customize semantic tokens and component props; use source changes in a fork when
+you need behavior outside the public API.
+
+## Why is there no add button command?
+
+The base set ships together in @flood-md/react: ten foundation primitives and
+eight native controls. Import the components you need; see the
+[base component set](base-components.md). The CLI provides init, init --dry-run
+and doctor.
+
+## Which package managers work?
+
+The installer uses npm. Other package managers can install the library manually,
+but their integration is not currently covered by the installer tests.
+
+## The controls look unstyled. What should I check?
+
+Import @flood-md/react/styles.css once at the app root. Doctor checks package
+versions and instruction files, not the application's stylesheet imports.
+Wrap a new interface in FloodRoot to select the neutral dark foundations profile.
+Outside that scope, controls retain the legacy theme. Check project CSS overrides
+if the import and wrapper are already present.
+
+## Can I rerun init or use it as an updater?
+
+Init refuses existing flood.json or owned instruction files. It does not overwrite
+project instructions. Follow the [upgrade guide](installation.md) and
+review customized instructions when moving to a new release.
+
+## Does making the website source public grant server access?
+
+No. Source visibility does not grant GitHub write access, hosting credentials or
+server execution. Browser-delivered HTML, JavaScript and CSS are visible to users
+regardless of repository visibility. This does not make a website immune to bugs:
+deployment permissions, dependencies and server behavior still need review.
+Credentials belong in service secret stores, never in a public or private Git repo.
+
+## Does Flood require an account or send my project to a service?
+
+No Flood account, backend or telemetry is required. The installer contacts npm to
+download packages. Components run inside your application and do not send project
+contents to Flood.
+
+## Where do I report problems?
+
+Use [GitHub issues](https://github.com/tillwithered/flood.md/issues) for reproducible
+bugs and API requests. For vulnerabilities, follow [SECURITY.md](../SECURITY.md)
+and avoid posting exploit details or credentials in a public issue.
+
+## Which fonts and icons does Flood use?
+
+Flood's component implementations are original. Fonts and icon artwork have their
+own authors and licenses:
+
+| Asset | Where it is used | License |
+| --- | --- | --- |
+| [Inter](https://github.com/rsms/inter) | Locally bundled variable font in the React stylesheet | [SIL Open Font License 1.1](/licenses/inter.txt) |
+| [Lucide](https://github.com/lucide-icons/lucide) | Website icons and documentation examples | [ISC, with included Feather-derived MIT notices](/licenses/lucide.txt) |
+| [GitHub Primer Octicons](https://github.com/primer/octicons) | GitHub link mark on the website | [MIT](/licenses/github-mark.txt) |
+
+The React component package does not depend on an icon pack. IconSlot and
+IconButton accept SVG artwork from the host. Examples importing `lucide-react`
+require that optional dependency in your project; you may substitute your own
+icons. Preserve the corresponding license notices when redistributing assets.
+The full Inter font provenance and license accompany the installed package.

package/dist/materials/guide-foundations.md

@@ -0,0 +1,275 @@
+# Foundations tokens · 0.2.11 candidate
+
+This guide describes the **0.2.11 candidate** foundation exports. Keep Flood packages at
+matching exact versions. Existing 0.1.1 installs use their earlier token contract.
+
+Foundations separates fixed reference values (`ref`) from semantic roles (`sys`).
+The compiler also supports component aliases (`comp`) and isolated experiments
+(`exp`); no component-specific tokens are shipped in this first profile.
+
+The 0.2.3 neutral dark profile has 168 public semantic roles. Five roles added
+since 0.2.2 define scrollbar size, inset, minimum
+thumb length and thumb/rest-hover colors. Geometry uses rem; the viewport stays
+natively scrollable and overlay tracks reserve no layout gutter. Version 0.2.2 adds
+`sys.type.display.*` (5.5rem size, 1.12 line height, 500 weight, -.04em tracking)
+for marketing headings, `sys.type.lead.*` (1.375rem, 1.45, 400, -.01em) for
+supporting marketing copy, and `sys.font.mono` for code. Existing product typography
+retains its metrics. Responsive page composition remains the host's responsibility.
+
+## Use the neutral dark profile
+
+```tsx
+import "@flood-md/tokens/foundations.css";
+
+<section data-flood-foundations="neutral" data-flood-theme="dark">
+  <p className="example">Content</p>
+</section>;
+```
+
+```css
+.example {
+  color: var(--flood-sys-color-content-default);
+  background: var(--flood-sys-color-surface-canvas);
+}
+```
+
+Both attributes belong on the same scope element. This opt-in token stylesheet
+defines tokens and `color-scheme`; React components adopt these roles inside
+`FloodRoot` when the React stylesheet is imported. It does not enable an
+incomplete light theme. The preset and theme are
+separate dimensions. Only `neutral` + `dark` is currently supplied.
+
+## Inspect names and decisions
+
+```ts
+import { tokenNames, type TokenName } from "@flood-md/tokens/foundations";
+
+const role: TokenName = "sys.color.content.default";
+const cssVariable = tokenNames[role]; // --flood-sys-color-content-default
+```
+
+`foundations.manifest.json` describes public roles, types, status, usage limits,
+resolved values, aliases and dependencies for each supplied context. Internal
+reference tokens are absent from the TypeScript lookup and are not listed as
+public manifest entries; alias/dependency metadata can still name their IDs.
+`neutral.dark.tokens.json` is a resolved diagnostic DTCG document including the
+internal reference graph's values. Internal names are not customization promises.
+
+The dark profile covers surfaces, content, filled primary/subtle actions,
+contextual ghost actions, field and feedback colors, focus, typography, spacing,
+radii, control sizing, motion and local stacking levels. Subtle content is for
+short supplementary metadata, not a universal small-body-text color or an
+automatic APCA pass. Required small helper text uses `sys.color.content.helper`.
+
+### Role families
+
+All IDs below have the `sys.` prefix; CSS names replace dots with hyphens and
+prepend `--flood-`. The generated typed lookup is the complete contract.
+
+| Family | Roles |
+| --- | --- |
+| `font` | `sans` (Inter, Arial, sans-serif), `mono` |
+| `type` | `display`, `lead`, `large`, `page`, `section`, `body`, `compact`, `label`, `helper`, `control`; each has `size`, `line-height`, `weight`, `tracking` |
+| `space` | `0`, `1`, `2`, `3`, `4`, `6`, `8`, `12`; one step = .25rem |
+| `radius` | `field` 1rem, `block` 1.5rem, `surface` 2rem, `action` pill, `indicator` .375rem |
+| `control` | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`; each has `height`, `text-size`, `line-height`, `padding-inline`, `icon-size`, `gap` |
+| `size` | `touch`, `choice`, `switch-width`, `switch-height`, `switch-thumb`, `indicator.sm/md/lg`, `keycap.sm/md/lg`, `container.sm/md/lg`, `grid.min-item` |
+| `color.action` | `primary`, `subtle`, `on-surface`, `ghost`; each has `rest`, `hover`, `pressed`, `content`, `disabled`, `disabled-content`; destructive action content has its own `danger.content` |
+| `color.field` | `background`, `border`, `boundary`, `content`, `placeholder`, `disabled`, `disabled-content` |
+| `color.feedback` | `error`, `success`, `warning`, `info` |
+| `color.selection` | `background`, `content` |
+| `focus`, `stroke` | Focus width/offset and decorative stroke width; independent of field validation |
+| `scrollbar` | `size`, `inset`, `min-thumb`; thumb colors live under color.scrollbar |
+| `color` | Surface/content, decorative border/divider, accent, focus, loading placeholder, indicator track/fill/accent and scrollbar rest/hover |
+| `motion` | `duration-fast`, `duration-normal`, `duration-reduced`, `easing` |
+| `layer` | `base`, `sticky`, `popover`, `modal`, `toast` |
+
+### Material and nested control context
+
+Absolute `color.surface.canvas/default/raised/overlay/floating` roles describe
+materials. A component that draws a material establishes the context for its
+children: Surface, Dialog/Drawer, anchored popups and selection menus, Toast,
+Toolbar/BulkActionBar, standalone Calendar and other shared material owners.
+Stack, Inline, Grid and other transparent layout wrappers inherit that context.
+Nesting a default Surface inside an overlay returns to the default material;
+DOM depth does not increment elevation.
+
+Neutral actions, fields, read-only/disabled fills, choices, selection, supporting
+chips/keycaps, skeletons and progress tracks consume inherited semantic roles.
+On filled materials, `color.context.filled.*` supplies translucent neutral state
+overlays: secondary actions use white 5% / 8% / 12% at rest / hover / press,
+fields use 5%, and quiet borders use 8%. This keeps a secondary action secondary
+on both a card and a floating panel. The canvas retains its established defaults.
+Primary actions, content, focus and semantic feedback colors remain independent.
+
+`color.surface.current` supplies the opaque material base for tinted feedback;
+`surface.supporting`, `surface.muted`, `surface.avatar` and `field.readonly`
+separate contextual fills from the absolute canvas color. Do not repurpose canvas
+to recolor controls: it also supplies contrasting content and document/media wells.
+
+Automatic owners require no extra Button/Input props. For an application-owned
+material boundary, `data-flood-surface="base|filled|floating"` selects the neutral
+control context. The attribute does not paint a background or implement a popup.
+Choose the actual material and override `color.surface.current` on that same
+scope if it differs from Flood's material. A transparent wrapper should not
+declare another material context.
+
+Customize contextual recipes using `--flood-sys-color-context-filled-*` and
+`--flood-sys-color-context-base-*` at the root. A direct consumer role override
+on the material owner can refine one scope; a canvas-only field override does
+not silently replace all elevated recipes. Review both contexts when opting into
+strong boundaries. The generated manifest is the complete list of roles.
+
+Floating panels use an opaque fallback, with glass enabled only where supported.
+`prefers-reduced-transparency: reduce` and `data-flood-transparency="reduced"`
+on a FloodRoot or an owning subtree request opaque panels without backdrop blur.
+Forced colors retain system backgrounds, boundaries and selection indicators.
+Translucency is a visual recipe, not an accessibility guarantee: inspect the
+composited background, content contrast and focus in the actual host.
+
+### Inter typography
+
+Size equivalents assume a 16px root for illustration. Flood does not set the
+host's root font size. Sizes use rem, line heights use ratios and tracking uses
+em. Font weights are 400/500. The React stylesheet bundles the Inter variable
+normal/italic fonts and their SIL Open Font License; it loads locally from the installed package.
+The token-only stylesheet does not load fonts: token-only consumers supply
+their own font setup with Latin/Cyrillic coverage as needed. Fallback metrics
+can differ.
+
+| Role | Size / line height | Weight | Tracking |
+| --- | --- | --- | --- |
+| display | 88 / 98.56 | 500 | -.04em |
+| lead | 22 / 31.9 | 400 | -.01em |
+| large | 32 / 40 | 500 | -.02em |
+| page | 24 / 32 | 500 | -.02em |
+| section | 20 / 28 | 500 | -.015em |
+| body | 16 / 24 | 400 | -.01em |
+| compact | 14 / 20 | 400 | -.01em |
+| label | 13 / 18 | 400 | -.01em |
+| helper | 12 / 18 | 400 | -.01em |
+| control | 14 / 20 | 500 | -.005em |
+
+Control heights are 24/28/32/40/44/48/56px equivalents. Their icon sizes are
+14/16/16/20/20/24/24px equivalents. These are minimum visual heights, not fixed
+clipping boxes. Touch target size, neighboring targets, long translations and
+increased text spacing require separate checks. Small controls are not ordinary
+text-field defaults.
+
+### Boundaries, focus and motion
+
+Version 0.2.3 uses the quiet `color.field.border` (#383838), matching the
+container-outline tone, for ordinary Input, Textarea, Select, unchecked choices,
+Switch and outline Button borders. It is one uniform perimeter, with no extra
+bottom edge or inset contour. The stronger `color.field.boundary` (#8a8a8a)
+remains available for an explicit contrast requirement; it is not the default.
+
+The quiet outline and field fill do not reach 3:1 against neighboring dark
+surfaces. This visual profile therefore does not establish WCAG 1.4.11 compliance
+for controls whose recognition depends on those signals. Preserve labels and
+evaluate the complete host composition; use a stronger role when required.
+Text contrast and APCA guidance remain separate from outline styling.
+
+A host can opt into stronger fields without overriding the independent focus role:
+
+```css
+/* Import after the Flood stylesheet; apply this attribute to FloodRoot. */
+.flood-root[data-control-contrast="strong"] {
+  --flood-sys-color-field-border: var(--flood-sys-color-field-boundary);
+}
+```
+
+Error, selected and focus
+states need semantic markup and a visible cue beyond color where applicable.
+
+Focus uses `focus.width` 2px and `focus.offset` 0px. `color.focus.ring` currently
+uses provisional pink #ff5ca8; it is configurable and is not a finalized brand
+palette. It must remain visible when error or selected styles are present.
+Color-pair tests cover supplied dark surfaces; these are not a whole-component
+WCAG or APCA conformance claim. Validate text role, size and weight together.
+
+For example, APCA `apca-w3` 0.1.9 gives white text on canvas Lc −106.77,
+helper #ededed on canvas Lc −95.00 (overlay: −91.00), and subtle #b2b2b2 on
+overlay Lc −55.54. These values do not certify the 12px/400 helper recipe:
+that version's font lookup recommends approximately 15.5px at weight 400 for
+Lc 95. Small helper text is a compact supporting role; provide readable main
+instructions and validate the actual content, device and enlargement behavior.
+Do not use subtle text or feedback accent colors for small required instructions
+merely because a WCAG color-pair calculation passes.
+
+Motion values are an initial interaction recipe: 100ms fast, 160ms normal,
+0ms reduced, with state easing. Consumers must apply the reduced value under
+`prefers-reduced-motion: reduce` and avoid relying on motion to convey state.
+Layer values express local order only; they do not implement portals, trapping
+focus, dismissal, scroll locking or an overlay stack.
+
+## Override and scope
+
+Override a public `sys` variable on its scope element, using inline styles or a
+stylesheet loaded afterward. Aliases remain CSS `var()` references. Nested
+scopes repeat both attributes so dependent aliases resolve against the nested
+values rather than inheriting already computed aliases from the parent.
+
+Arbitrary descendant overrides without a new scope are not supported. Portal
+containers must explicitly receive the same scope attributes and overrides.
+Changing an internal `ref` value is useful for diagnostics but not a stable API.
+
+## Source and compiler profile
+
+Only `packages/tokens/src/tokens.json` authors values. Its versioned Flood
+envelope contains `legacy`, `sets.shared`, `sets.palette`, `sets.theme` and
+`presets`. This envelope is not itself a DTCG Format document. Sets contain
+nested tokens with explicit `$type`, `$value`, `$description` and `md.flood`
+metadata. Build artifacts are generated and must not be edited.
+
+The first compiler profile supports sRGB color, nonnegative px/rem dimension,
+signed em dimension (for tracking),
+ms/s duration, finite number, numeric fontWeight, fontFamily and cubicBezier.
+Aliases refer to whole tokens using `{sys.color.content.default}` syntax.
+Composite types, JSON Pointer references, group inheritance, density modifiers,
+other color spaces and the full DTCG Resolver API are not supported; unsupported
+input fails instead of being silently coerced. This is not a full DTCG
+implementation or a claim of accessibility conformance.
+
+Build rejects missing/cyclic references, mismatched types, overlapping sets,
+invalid names and CSS-name collisions, disallowed layer dependencies,
+cross-component aliases, and stable-to-experimental dependencies. All supplied
+contexts must expose the same public role/type contract. Palette/reference
+values are fixed; themes choose roles instead of changing reference values.
+
+## Compatibility
+
+Existing `@flood-md/tokens` JSON and `tokens.css` retain their shared/light/dark
+contract and `--flood-*` names. Existing React controls outside `FloodRoot` keep
+using those tokens; old custom overrides continue to apply there. Inside
+`FloodRoot`, the dark foundation roles control the component recipe. Legacy
+overrides do not automatically override separately scoped foundation roles.
+
+Version 0.2.2 adds these exports without replacing an existing npm version.
+Publication must be verified separately; source version numbers are not proof.
+
+
+Version 0.2.5 adds twenty-five semantic roles, bringing the dark profile
+to 193 roles. Existing role values remain unchanged:
+
+- sys.color.accent.content and sys.color.loading.placeholder separate accent text
+  and loading fills from focus and action states.
+- sys.color.indicator.track/fill/accent and sys.size.indicator.sm/md/lg control
+  bounded indicators without borrowing control or focus roles.
+- sys.color.action.danger.content styles destructive actions independently from
+  validation messages and keyboard focus.
+
+- sys.size.keycap.sm/md/lg provide independent relative heights for keyboard hints.
+
+- sys.size.container.sm/md/lg and sys.size.grid.min-item supply relative layout bounds.
+
+
+The 0.2.5 separates floating surfaces from modal surfaces.
+The floating material uses nine of those new semantic roles; previous token
+values remain intact. surface.floating is the opaque fallback;
+surface.floating-translucent, border.floating, selection.floating, shadow.floating
+and effect.floating blur/saturation/shadow-offset/shadow-blur define the floating
+material. Select, Combobox, MultiSelect, Menu, Popover and Tooltip share it; Dialog
+and Drawer retain surface.overlay. Backdrop filtering is progressive enhancement;
+reduced transparency uses the opaque fill and forced colors use system colors.
+Keep text opaque and evaluate it against the actual composited background.

package/dist/materials/guide-installation.md

@@ -0,0 +1,79 @@
+# Installation · 0.2.11
+
+The commands below target version 0.2.11. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
+
+Use Node.js 22.12 or newer and an existing npm-based React/Next.js project.
+React 18.3/19 is supported; React 19 and Next.js App Router are integration targets.
+
+## Connect once, import by name
+
+The base set ships in one package. Set it up once for your project, then use
+named imports such as `import { Button, Input } from "@flood-md/react"`.
+There is no per-component `add` command or source-copy registry. You do not
+repeat installation when you start using another component.
+
+## Connect with the CLI
+
+```sh
+npx @flood-md/cli@0.2.11 init --dry-run
+npx @flood-md/cli@0.2.11 init
+```
+
+The installer adds exact matching tokens, React and agent packages. It creates
+`flood.json`, `flood/DESIGN.md` and `.agents/skills/flood-ui/SKILL.md`, preserves
+host instructions and refuses existing files or linked destinations. It does
+not modify application source. Import CSS once in the React entry or Next
+`app/layout.tsx`, then wrap new UI in `FloodRoot`:
+
+```tsx
+import "@flood-md/react/styles.css";
+import { Button, FloodRoot } from "@flood-md/react";
+
+export function App() {
+  return <FloodRoot><Button>Start something</Button></FloodRoot>;
+}
+```
+
+Use a client component for callbacks, state or Field's function child. See
+[components](components.md) and the [base inventory](base-components.md).
+No Tailwind configuration or font CDN is needed. The foundations profile is dark
+only; legacy theme behavior remains available outside `FloodRoot`.
+
+```sh
+npx @flood-md/cli@0.2.11 doctor
+```
+
+Doctor checks package versions and guide presence, not stylesheet imports or
+application behavior. If your agent does not discover the installed skill,
+reference `flood/DESIGN.md` from its existing instructions.
+
+## Manual package installation
+
+```sh
+npm install --save-exact @flood-md/tokens@0.2.11 @flood-md/react@0.2.11 @flood-md/agent@0.2.11
+```
+
+Import the stylesheet and use `FloodRoot` as above. Manual installation does not
+create the CLI's project configuration or copied instruction files; read the
+matching agent package's guides directly or use CLI init in an unconfigured
+project. All components ship together and are imported by name.
+
+## Updates from 0.1.1
+
+Upgrade tokens, React and agent together to the same exact version. Existing
+controls outside `FloodRoot` retain their earlier theme behavior. Adopt the new
+dark recipes explicitly by adding `FloodRoot`; move customization to scoped
+`--flood-sys-*` roles instead of assuming old variables change the new profile.
+
+Compare the new package's agent guides with customized local copies before
+updating them. Update `flood.json` after a successful migration and run the
+matching CLI doctor. Do not rerun init to overwrite existing instructions.
+Run the host build/tests and browser checks after upgrading.
+
+## Evaluate repository changes locally
+
+For source development, run `npm ci` and `npm run build:packages`, then
+`npm pack --workspace=@flood-md/tokens` (and likewise React/agent). Install the
+three generated tarballs together using their local paths with
+`npm install --save-exact`. This evaluates local source without implying that a
+future version is already available from the registry.

package/dist/materials/guide-interface-content.md

@@ -0,0 +1,76 @@
+# Interface content
+
+Flood's interface-content workflow covers the information and wording in a UI:
+labels, actions, hierarchy, hints, states and adaptation of reference content.
+It is separate from typography sizing. Use it when introducing visible copy or
+reviewing an existing interface; it does not authorize rewriting user documents.
+
+## Start with the task
+
+Identify the user, their current task and the state they are in. Give each text
+element a purpose: identify, distinguish, guide, explain a relevant consequence,
+report a real state or support recovery. Keep, rewrite, move or remove it based
+on that purpose. A component's optional description prop is not a requirement to
+write a description.
+
+An invoice list can simply be titled “Invoices”. A category label, the same noun
+in a heading and a sentence describing the obvious workflow need separate reasons
+to remain. Necessary breadcrumbs, section headings and the printed document's
+own title still have valid jobs; there is no universal maximum heading count.
+
+During completion, review each supporting sentence in screen order and record
+its new information. If it only narrates the obvious next action, leave the
+optional slot empty. The optional @flood-md/agent/inspect browser observer can
+inventory copy and geometry; it cannot judge whether a sentence belongs in the
+product. See [rendered review](/agent/references/rendered-review.md).
+
+## Concise content keeps necessary detail
+
+Remove routine narration, decorative assurances and implementation facts that do
+not affect the task. An ordinary preview does not need to announce its embedded
+fonts. An export-format choice may need to explain selectable text. A field may
+need a non-obvious unit or constraint. A destructive action may need a clear
+consequence. Do not hide essential information just to reduce visible text.
+
+Name actions by their actual result and preserve accessible names. An error
+should support recovery; success must match a completed operation. Local
+validation does not establish expert review. A PDF export is not a restorable
+backup of editable records. Sample-data distinctions belong where they prevent
+a real misunderstanding, rather than repeated throughout an established test host.
+
+## Learn from references in context
+
+Transfer the question a pattern answers, then use the host's actual objects,
+actions and states. A bill-processing product's approval or payment stages do
+not become capabilities of an invoice generator because their layout is useful.
+Its promotional language is not a vocabulary for the host's working interface.
+
+See the full [interface content skill](/agent/references/flood-interface-content/SKILL.md)
+and [decision examples](/agent/references/interface-content-examples.md). The
+matching installed CLI can discover and read workflow:interface-content. This
+additive guidance is part of 0.2.11; installed projects
+keep their current versions and customized guide copies.
+
+## Review the result
+
+Read the composed screen in task order. Check visible and accessible copy,
+repeated meaning across regions and the state after an action. Remove empty
+wrappers or reserved gaps when a subtitle or banner is removed. Explain important
+editorial decisions in the review, rather than adding those explanations to the UI.
+Phrase scans and word counts cannot establish content quality or agent compliance.
+
+Further reading: [Fluent content design](https://fluent2.microsoft.design/content-design)
+relates content to user intent and timing; [DWP hint guidance](https://design-system.dwp.gov.uk/guidance/hint-text)
+asks whether a hint is needed; [GOV.UK error messages](https://design-system.service.gov.uk/components/error-message/)
+connect failure to recovery. These inform the workflow; their service-specific
+wording and punctuation conventions are not universal Flood rules.
+
+## Prototype context
+
+An explicitly requested local prototype does not require a permanent Demo or
+Prototype badge in the shell. Keep provenance and implementation limits in its
+README/test handoff. A visible distinction still belongs beside an affected
+record, choice or action when it changes interpretation, such as sample records
+mixed with real data or an existing simulation/live choice. Preserve accurate
+action and media names; removing a badge does not imply real connectivity or
+delivery. Draft, Pending and Offline remain meaningful record states.

package/dist/materials/guide-introduction.md

@@ -0,0 +1,42 @@
+# Flood documentation
+
+Flood provides original React components, semantic CSS tokens and versioned
+instructions for coding agents. Start with the guide for your task:
+
+The website renders these guides at [/docs](https://flood.md/docs) and provides
+live examples at [/components](https://flood.md/components). Edit the Markdown
+here and review changes through a pull request; the next website build includes
+them without a separate content service.
+
+| Guide | What it covers |
+| --- | --- |
+| [Skills](skills.md) | Task-focused composition and verification workflows |
+| [Interface content](interface-content.md) | Editorial decisions, purposeful copy and contextual reference adaptation |
+| [Installation](installation.md) | React, Next.js, CLI setup and manual installation |
+| [Project UI](project-ui.md) | Optional semantic @/ui/button imports in your application |
+| [Layout](layout.md) | Intrinsic actions, responsive forms, choice sizing, gaps and hierarchy |
+| [Components](components.md) | Available controls, props and form composition |
+| [Base component inventory](base-components.md) | Available primitives and controls in the base release |
+| [Customization](theming.md) | Scoped dark foundations overrides and legacy theme boundaries |
+| [Foundations](foundations.md) | Typed semantic tokens and neutral dark profile for 0.2.11 |
+| [Agents](agents.md) | Installing and using the matching agent instructions |
+| [Agent knowledge](agent-knowledge.md) | Versioned discovery, selected reads and preserved project guides |
+| [FAQ](faq.md) | Compatibility, customization, updates and common problems |
+| [Command palette](recipes/command-palette.md) | Compose Dialog and CommandList with host-owned actions |
+| [Table bulk actions](recipes/table-bulk-actions.md) | Controlled cross-page selection and local confirmation |
+| [Grouped form](recipes/grouped-form.md) | Shared tracks, semantic groups and optional fields |
+| [Record management](recipes/record-management.md) | Search, filter and edit records without losing the working list |
+| [Settings workspace](recipes/settings-workspace.md) | Group settings, validate a draft and save changes |
+
+## Versions
+
+This branch documents **version 0.2.11**; source availability does
+not establish npm publication. Use matching exact versions of the Flood packages. Documentation on `main` can describe later work; the
+[release tags](https://github.com/tillwithered/flood.md/releases) preserve the
+source and docs for each release. Installed `flood/DESIGN.md` takes precedence
+over website guidance when working in an existing project.
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md), [architecture](architecture.md),
+[releases](releases.md) and the [security policy](../SECURITY.md).