@flood-md/agent 0.2.9 → 0.2.11

package/dist/materials/token-sys.type.section.size.json

@@ -0,0 +1,34 @@
+{
+  "role": "sys.type.section.size",
+  "cssName": "--flood-sys-type-section-size",
+  "description": "section text size",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.type.section.size",
+      "type": "dimension",
+      "cssName": "--flood-sys-type-section-size",
+      "description": "section text size",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.0",
+      "usage": {
+        "allowed": [
+          "section text size"
+        ],
+        "avoid": []
+      },
+      "value": {
+        "value": 1.25,
+        "unit": "rem"
+      },
+      "alias": "ref.type.section.size",
+      "dependencies": [
+        "ref.type.section.size"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.type.section.tracking.json

@@ -0,0 +1,34 @@
+{
+  "role": "sys.type.section.tracking",
+  "cssName": "--flood-sys-type-section-tracking",
+  "description": "section text tracking",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.type.section.tracking",
+      "type": "dimension",
+      "cssName": "--flood-sys-type-section-tracking",
+      "description": "section text tracking",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.0",
+      "usage": {
+        "allowed": [
+          "section text tracking"
+        ],
+        "avoid": []
+      },
+      "value": {
+        "value": -0.015,
+        "unit": "em"
+      },
+      "alias": "ref.type.section.tracking",
+      "dependencies": [
+        "ref.type.section.tracking"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.type.section.weight.json

@@ -0,0 +1,31 @@
+{
+  "role": "sys.type.section.weight",
+  "cssName": "--flood-sys-type-section-weight",
+  "description": "section text weight",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.type.section.weight",
+      "type": "fontWeight",
+      "cssName": "--flood-sys-type-section-weight",
+      "description": "section text weight",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.0",
+      "usage": {
+        "allowed": [
+          "section text weight"
+        ],
+        "avoid": []
+      },
+      "value": 500,
+      "alias": "ref.type.section.weight",
+      "dependencies": [
+        "ref.type.section.weight"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/knowledge.json

@@ -0,0 +1,522 @@
+{
+  "schemaVersion": 1,
+  "groups": [
+    {
+      "id": "foundations",
+      "name": "Foundations",
+      "description": "Semantic colors, type, geometry, spacing and scoped customization."
+    },
+    {
+      "id": "composition",
+      "name": "Composition",
+      "description": "Layout and task recipes assembled from existing primitives."
+    },
+    {
+      "id": "interaction",
+      "name": "Interaction",
+      "description": "Forms, selection, navigation and transient layers."
+    },
+    {
+      "id": "data-feedback",
+      "name": "Data & feedback",
+      "description": "Structured content, files and honest operation states."
+    },
+    {
+      "id": "quality",
+      "name": "Quality",
+      "description": "Accessibility, evidence and regression checks."
+    },
+    {
+      "id": "motion",
+      "name": "Motion",
+      "description": "Component motion roles, transition recipes and reduced-motion verification."
+    }
+  ],
+  "workflows": {
+    "motion": ["motion", "quality"],
+    "composition": [
+      "composition"
+    ],
+    "spacing": [
+      "foundations",
+      "composition"
+    ],
+    "foundations": [
+      "foundations"
+    ],
+    "accessibility": [
+      "quality"
+    ],
+    "forms": [
+      "interaction"
+    ],
+    "overlays": [
+      "interaction"
+    ],
+    "navigation": [
+      "interaction"
+    ],
+    "data-display": [
+      "data-feedback"
+    ],
+    "feedback": [
+      "data-feedback"
+    ],
+    "verification": [
+      "quality"
+    ],
+    "interface-content": [
+      "composition",
+      "quality"
+    ],
+    "hierarchy": [
+      "foundations",
+      "composition"
+    ],
+    "records": [
+      "data-feedback",
+      "composition"
+    ]
+  },
+  "references": [
+    {
+      "id": "guide:entry",
+      "source": "SKILL.md",
+      "groups": [
+        "composition"
+      ],
+      "name": "Flood agent entry",
+      "description": "Start with host instructions and the installed version, then choose only relevant guidance."
+    },
+    {
+      "id": "guide:design",
+      "source": "DESIGN.md",
+      "groups": [
+        "foundations",
+        "composition"
+      ],
+      "name": "Installed design contract",
+      "description": "The version-matched component, token and ownership contract."
+    },
+    {
+      "id": "reference:routing",
+      "source": "references/routing.md",
+      "groups": [
+        "quality"
+      ],
+      "name": "Sources and routing",
+      "description": "Choose which installed source governs a task and how to verify it."
+    },
+    {
+      "id": "reference:composition",
+      "source": "references/composition.md",
+      "groups": [
+        "composition"
+      ],
+      "name": "Screen composition",
+      "description": "Assemble application layouts and native forms from existing Flood primitives."
+    },
+    {
+      "id": "reference:spacing",
+      "source": "references/spacing.md",
+      "groups": [
+        "foundations",
+        "composition"
+      ],
+      "name": "Spacing reference",
+      "description": "Measure relationships, density, nesting and usable targets."
+    },
+    {
+      "id": "reference:accessibility",
+      "source": "references/accessibility.md",
+      "groups": [
+        "quality"
+      ],
+      "name": "Accessibility reference",
+      "description": "Names, keyboard, focus, reflow and perception checks for the actual host."
+    },
+    {
+      "id": "reference:customization",
+      "source": "references/customization.md",
+      "groups": [
+        "foundations"
+      ],
+      "name": "Scoped customization",
+      "description": "Apply a host brand through scoped semantic overrides without editing dependencies or creating a parallel token system."
+    },
+    {
+      "id": "reference:verification",
+      "source": "references/verification.md",
+      "groups": [
+        "quality"
+      ],
+      "name": "Verification reference",
+      "description": "Turn applicable guidance into executed checks and report their limits."
+    },
+    {
+      "id": "reference:knowledge",
+      "source": "references/knowledge.md",
+      "groups": [
+        "quality"
+      ],
+      "name": "Knowledge discovery and growth",
+      "description": "Read matching guidance, preserve host customizations and extend the knowledge catalog without silent drift."
+    },
+    {
+      "id": "reference:rules",
+      "source": "rules.json",
+      "groups": [
+        "quality"
+      ],
+      "name": "Observable rule index",
+      "description": "Find stable rule IDs and their applicable checks; this index is not execution evidence."
+    },
+    {
+      "id": "reference:workflow-index",
+      "source": "workflows.json",
+      "groups": [
+        "quality"
+      ],
+      "name": "Workflow applicability index",
+      "description": "Find applicable component-family workflows without treating applicability as proof."
+    },
+    {
+      "id": "reference:interface-content-examples",
+      "source": "references/interface-content-examples.md",
+      "groups": [
+        "composition",
+        "quality"
+      ],
+      "name": "Interface content decisions",
+      "description": "Contextual examples of removing filler while preserving labels, consequences, recovery and document content."
+    },
+    {
+      "id": "reference:rendered-review",
+      "source": "references/rendered-review.md",
+      "groups": [
+        "quality",
+        "composition"
+      ],
+      "name": "Rendered interface review",
+      "description": "Read-only DOM observations for icon ownership and mixed-row alignment, with separate contextual copy and hierarchy review."
+    },
+    {
+      "id": "reference:record-decisions",
+      "source": "references/record-decisions.md",
+      "groups": [
+        "data-feedback",
+        "composition"
+      ],
+      "name": "Record metadata decisions",
+      "description": "Contextual list/detail, comparison, category/state, priority and timestamp decisions across different tasks."
+    },
+    {
+      "id": "reference:component-families",
+      "source": "references/component-families.md",
+      "groups": [
+        "composition",
+        "foundations",
+        "quality"
+      ],
+      "name": "Component family authoring",
+      "description": "Build reusable components that share Flood anatomy, sizing, geometry and state contracts; compare rendered siblings before introducing a new recipe."
+    }
+  ],
+  "componentGroups": {
+    "setup": [
+      "foundations"
+    ],
+    "typography": [
+      "foundations"
+    ],
+    "layout": [
+      "composition"
+    ],
+    "actions": [
+      "interaction"
+    ],
+    "forms": [
+      "interaction"
+    ],
+    "overlays": [
+      "interaction"
+    ],
+    "navigation": [
+      "interaction"
+    ],
+    "content": [
+      "data-feedback"
+    ],
+    "feedback": [
+      "data-feedback"
+    ]
+  },
+  "capabilities": [
+    {
+      "id": "dark-foundations",
+      "status": "available",
+      "description": "The existing neutral dark profile and scoped semantic customization.",
+      "materials": [
+        "workflow:foundations",
+        "reference:customization"
+      ]
+    },
+    {
+      "id": "component-motion-tokens",
+      "status": "available",
+      "description": "Semantic timing, easing, travel and reduced-motion roles for component states.",
+      "materials": [
+        "workflow:motion",
+        "token:sys.motion.duration-press",
+        "token:sys.motion.duration-enter",
+        "token:sys.motion.duration-layer",
+        "token:sys.motion.duration-exit",
+        "token:sys.motion.duration-fast",
+        "token:sys.motion.duration-normal",
+        "token:sys.motion.duration-reduced",
+        "token:sys.motion.easing"
+      ]
+    },
+    {
+      "id": "page-transitions",
+      "status": "not-provided",
+      "description": "No Flood page-transition component or router-lifecycle workflow is supplied.",
+      "materials": []
+    },
+    {
+      "id": "additional-foundation-themes",
+      "status": "not-provided",
+      "description": "The new foundations profile provides dark only; legacy light controls do not add another foundation theme.",
+      "materials": []
+    },
+    {
+      "id": "manual-search-collections",
+      "status": "available",
+      "description": "Host-owned query/results identity, pending/error/retry and retained selection; no network client.",
+      "materials": [
+        "component:combobox",
+        "component:multi-select",
+        "component:autocomplete"
+      ]
+    },
+    {
+      "id": "server-table-pages",
+      "status": "available",
+      "description": "Explicit controlled page/sort and selection scope for supplied server pages; host owns fetching and authorization.",
+      "materials": [
+        "component:data-table",
+        "recipe:record-workspace"
+      ]
+    },
+    {
+      "id": "collection-view-recipe",
+      "status": "available",
+      "description": "Typed host recipe for local query drafts and persisted enum-filter/sort views, shared by a table and file list; no new runtime export or remote query service.",
+      "materials": [
+        "recipe:collection-views"
+      ]
+    },
+    {
+      "id": "navigation-workspace-recipe",
+      "status": "available",
+      "description": "Host composition of Sidebar profiles for global modules and contextual pages, independent visibility and scoped focus/query state; no additional GlobalRail runtime export.",
+      "materials": [
+        "component:sidebar",
+        "recipe:navigation-workspace",
+        "workflow:navigation"
+      ]
+    }
+  ],
+  "documentGroups": {
+    "recipes/record-management.md": ["data-feedback", "composition"],
+    "recipes/settings-workspace.md": ["interaction", "composition"],
+    "README.md": [
+      "composition"
+    ],
+    "installation.md": [
+      "quality"
+    ],
+    "project-ui.md": [
+      "composition"
+    ],
+    "foundations.md": [
+      "foundations"
+    ],
+    "motion.md": ["foundations", "motion"],
+    "layout.md": [
+      "composition"
+    ],
+    "theming.md": [
+      "foundations"
+    ],
+    "agents.md": [
+      "quality"
+    ],
+    "skills.md": [
+      "quality"
+    ],
+    "agent-knowledge.md": [
+      "quality"
+    ],
+    "faq.md": [
+      "quality"
+    ],
+    "privacy.md": [
+      "quality"
+    ],
+    "recipes/command-palette.md": [
+      "composition",
+      "interaction"
+    ],
+    "recipes/select-all.md": [
+      "composition",
+      "interaction"
+    ],
+    "recipes/split-button.md": [
+      "composition",
+      "interaction"
+    ],
+    "recipes/form-submission.md": [
+      "composition",
+      "interaction"
+    ],
+    "recipes/filter-bar.md": [
+      "composition",
+      "data-feedback"
+    ],
+    "recipes/workspace-review.md": [
+      "composition",
+      "interaction"
+    ],
+    "recipes/table-bulk-actions.md": [
+      "composition",
+      "data-feedback",
+      "interaction"
+    ],
+    "interface-content.md": [
+      "composition",
+      "quality"
+    ],
+    "recipes/grouped-form.md": [
+      "composition",
+      "interaction"
+    ],
+    "recipes/record-workspace.md": [
+      "composition",
+      "data-feedback",
+      "quality"
+    ],
+    "recipes/collection-views.md": [
+      "composition",
+      "data-feedback",
+      "interaction",
+      "quality"
+    ],
+    "recipes/navigation-workspace.md": [
+      "composition",
+      "interaction",
+      "quality"
+    ]
+  },
+  "prerequisites": {
+    "workflow:forms": [
+      "workflow:composition"
+    ],
+    "workflow:overlays": [
+      "workflow:composition"
+    ],
+    "workflow:data-display": [
+      "workflow:composition"
+    ],
+    "recipe:command-palette": [
+      "workflow:composition",
+      "workflow:overlays",
+      "workflow:navigation"
+    ],
+    "recipe:select-all": [
+      "workflow:composition",
+      "workflow:forms"
+    ],
+    "recipe:split-button": [
+      "workflow:composition",
+      "workflow:navigation"
+    ],
+    "recipe:form-submission": [
+      "workflow:composition",
+      "workflow:forms",
+      "workflow:feedback"
+    ],
+    "recipe:filter-bar": [
+      "workflow:composition",
+      "workflow:forms",
+      "workflow:data-display"
+    ],
+    "recipe:workspace-review": [
+      "workflow:composition",
+      "workflow:forms",
+      "workflow:overlays"
+    ],
+    "recipe:table-bulk-actions": [
+      "workflow:composition",
+      "workflow:data-display",
+      "workflow:navigation"
+    ],
+    "recipe:grouped-form": [
+      "workflow:composition",
+      "workflow:forms",
+      "workflow:interface-content",
+      "workflow:hierarchy"
+    ],
+    "workflow:verification": [
+      "workflow:interface-content"
+    ],
+    "workflow:hierarchy": [
+      "workflow:interface-content"
+    ],
+    "workflow:records": [
+      "workflow:composition",
+      "workflow:interface-content",
+      "workflow:hierarchy"
+    ],
+    "recipe:record-management": [
+      "workflow:records",
+      "workflow:overlays",
+      "workflow:forms"
+    ],
+    "recipe:settings-workspace": [
+      "workflow:composition",
+      "workflow:forms",
+      "workflow:feedback"
+    ],
+    "recipe:record-workspace": [
+      "workflow:composition",
+      "workflow:hierarchy",
+      "workflow:forms",
+      "workflow:navigation",
+      "workflow:feedback",
+      "workflow:data-display",
+      "workflow:interface-content"
+    ],
+    "reference:component-families": [
+      "workflow:composition",
+      "workflow:foundations",
+      "workflow:spacing"
+    ],
+    "recipe:collection-views": [
+      "workflow:composition",
+      "workflow:forms",
+      "workflow:overlays",
+      "workflow:data-display",
+      "workflow:records",
+      "workflow:feedback",
+      "workflow:interface-content"
+    ],
+    "recipe:navigation-workspace": [
+      "workflow:composition",
+      "workflow:navigation",
+      "workflow:spacing",
+      "workflow:accessibility",
+      "workflow:interface-content"
+    ]
+  }
+}

package/lib/index.d.ts

@@ -0,0 +1,33 @@
+export type KnowledgeKind = 'guide' | 'workflow' | 'reference' | 'component' | 'recipe' | 'token';
+export interface KnowledgeGroup { id: string; name: string; description: string; }
+export interface KnowledgeCapability { id: string; status: 'available' | 'not-provided'; description: string; materials: string[]; }
+export interface KnowledgeMaterial {
+  id: string; kind: KnowledgeKind; name: string; description: string; groups: string[];
+  status: 'available'; file: string; bytes: number; sha256: string; links: string[];
+  requires: string[]; installedTarget?: string;
+}
+export interface KnowledgeCatalog { schemaVersion: 1; version: string; groups: KnowledgeGroup[]; capabilities: KnowledgeCapability[]; materials: KnowledgeMaterial[]; }
+export type KnowledgeSummary = Omit<KnowledgeMaterial, 'file' | 'bytes' | 'sha256' | 'links' | 'installedTarget'> & {relatedCount: number};
+export interface KnowledgePage {
+  schemaVersion: 1; version: string; fingerprint: string;
+  query: {kind: KnowledgeKind | null; group: string | null; search: string};
+  total: number; items: KnowledgeSummary[]; truncated: boolean; nextCursor: string | null;
+}
+export interface KnowledgeRead extends KnowledgeSummary {
+  schemaVersion: 1; version: string; fingerprint: string; source: 'package'; sha256: string;
+  installedTarget: string | null; links: string[]; linksOffset: number; nextLinksOffset: number | null; text: string; offset: number;
+  totalCharacters: number; truncated: boolean; nextOffset: number | null;
+}
+export interface KnowledgeInfo {
+  schemaVersion: 1; version: string; fingerprint: string; materialCount: number;
+  groups: (KnowledgeGroup & {count:number})[]; kinds: {kind:KnowledgeKind; count:number}[];
+  capabilities: KnowledgeCapability[];
+}
+export interface KnowledgeReader {
+  info(): Promise<KnowledgeInfo>;
+  list(query?: {kind?: KnowledgeKind; group?: string; search?: string; limit?: number; cursor?: string}): Promise<KnowledgePage>;
+  /** Offsets and lengths count Unicode code points, not UTF-8 bytes. */
+  read(id: string, range?: {offset?: number; length?: number; linksOffset?: number}): Promise<KnowledgeRead>;
+}
+export function validateKnowledgeCatalog(catalog: unknown): KnowledgeCatalog;
+export function createKnowledgeReader(options?: {root?: string}): KnowledgeReader;