@cassiomc1/forgeloop 1.0.0 → 1.1.1

package/.cursor/rules/project-loop.mdc

@@ -17,11 +17,12 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 5. Make the minimum change, run specific checks, and run proportional regression checks.
 6. Diagnose failures before fixing them; do not repeat attempts without new evidence.
 7. Request authority for unrelated actions, installations, and publications. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
-8. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
+8. Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.
+9. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 
 After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
 
-9. Report only demonstrated results and checks.
+10. Report only demonstrated results and checks.
 
 Do not stop for non-blocking missing product details. When a safe, reversible
 local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.

package/.github/copilot-instructions.md

@@ -14,6 +14,7 @@ Use these instructions across the repository while preserving local rules.
 - Make the smallest coherent change; validate with specific and regression checks.
 - Diagnose causes before fixing failures; do not make unverified attempts.
 - Do not install software, publish, delete, or alter external state without authority. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
+- Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.
 - After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 
 After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.

package/AGENTS.md

@@ -12,7 +12,8 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 1. Make the smallest coherent change, run specific checks, and proportional regression checks.
 1. Diagnose failures before fixing; do not repeat attempts without new evidence.
 1. Do not install software, publish, delete, or migrate data without authority. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
-1. Before implementation, create/validate `.forgeloop/current-contract.json`, persist routing, satisfy gates, and require `forgeloop preflight` to return `READY`.
+1. Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.
+1. Before implementation, create/validate the task contract (`contract.json`), persist routing, satisfy gates, and require `forgeloop preflight` to return `READY`.
 1. Before claiming `COMPLETE`, require `forgeloop complete` to return `VALID`; otherwise report completion as not protocol-verified.
 1. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 1. After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.

package/CLAUDE.md

@@ -14,6 +14,7 @@ When working in this repository:
 1. Make small changes, run specific checks, and run proportional regression checks.
 1. Investigate root causes before fixing failures; do not make unverified attempts.
 1. Request authority for unrelated installations, publications, deletions, or migrations. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
+1. Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.
 1. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 1. After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
 1. Report current evidence, limitations, and publication state without claiming checks that were not run.

package/DOCS_INDEX.md

@@ -7,6 +7,13 @@ integration and guide context. Use this map before editing documentation.
 
 | Need | Canonical source | Boundary |
 | --- | --- | --- |
+| Getting started tutorial | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) | First-time walkthrough from init to completion |
+| Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational handoff and multi-tool resumption |
+| CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
+| Artifact and schema reference | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) | Purpose, mutability, and trust classifications of `.forgeloop/` |
+| Troubleshooting and recovery | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Symptom-first recovery and stable error code reference |
+| Operational recipes | [`docs/RECIPES.md`](./docs/RECIPES.md) | Short copy-paste recipes for daily workflows |
+| Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
 | Lifecycle, gates, planning, verification, and recovery | [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) | Normative process for agents and developer workflows |
 | Capability levels, discovery, and degradation | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) | Vendor-neutral harness contract |
 | Durable project facts | [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) | Target-specific facts only; no prompts or secrets |
@@ -17,6 +24,35 @@ integration and guide context. Use this map before editing documentation.
 | Guide content | [`ENG/`](./ENG/) | Context-specific, English-only operational guides |
 | Diagram | [`docs/forgeloop-flow.mmd`](./docs/forgeloop-flow.mmd) | Canonical Mermaid source; SVG is generated output |
 
+## Audience map
+
+| I am a... | Start here |
+| --- | --- |
+| **First-time user or developer** | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) |
+| **AI coding agent / harness** | [`AGENTS.md`](./AGENTS.md) → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) |
+| **Harness integrator** | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) |
+| **Resuming another tool / session** | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) |
+| **Looking up CLI commands** | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) |
+| **Inspecting `.forgeloop/` files** | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) |
+| **Fixing a broken or stale state** | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) |
+| **Looking for quick recipes** | [`docs/RECIPES.md`](./docs/RECIPES.md) |
+| **Documentation contributor** | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) |
+| **Protocol architect / maintainer** | [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) + [`schemas/`](./schemas/) |
+| **Security auditor** | [`THREAT_MODEL.md`](./THREAT_MODEL.md) |
+| **Engineering guide author** | [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) + [`ENG/`](./ENG/) |
+
+## Task map
+
+- **Start my first task**: [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
+- **Resume after switching tools**: [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
+- **Check CLI options and syntax**: [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
+- **Understand what `.forgeloop/` stores**: [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
+- **Fix a blocked, stale, or invalid state**: [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)
+- **Find operational copy-paste commands**: [`docs/RECIPES.md`](./docs/RECIPES.md)
+- **Read the normative protocol specification**: [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
+- **Integrate a new AI environment**: [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
+- **Edit documentation safely**: [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md)
+
 `README.md` is intentionally a catalog and quickstart. Do not copy the full
 process into adapters or README sections; link to the canonical source.
 

package/ENG/design-code-eng.md

@@ -3,7 +3,7 @@ name: design-code-eng
 language: en
 description: "Visual direction, UX, motion, and perceived performance for premium digital experiences."
 version: "2026.09"
-last-reviewed: "2026-08-10"
+last-reviewed: "2026-08-17"
 guide-id: design
 requires-gates:
   - design
@@ -307,12 +307,42 @@ Canvas, WebGL, SVG displacement, and Liquid Glass effects follow the **normative
 - For charts and data visualization, consult [TanStack Charts](https://github.com/TanStack/charts); preserve responsiveness, contrast, keyboard readability, and never rely on color alone to communicate series or states.
 - For subtle interaction sounds, consult [Cuelume](https://cuelume-site.pages.dev/); provide volume/mute controls and never rely on audio to communicate essential information.
 
+### Architecture and diagram design — Beautiful Mermaid
+
+When a task benefits from a polished technical diagram — for example an
+architecture flow, lifecycle, state machine, sequence, class, ER, or other
+Mermaid-supported visualization — consider
+[Beautiful Mermaid by Craft](https://agents.craft.do/mermaid) as an optional
+design/rendering resource.
+
+Use the live editor at
+[agents.craft.do/mermaid/editor](https://agents.craft.do/mermaid/editor) to
+preview and refine Mermaid source and, when appropriate, export a polished SVG.
+
+Rules:
+
+- Mermaid source remains the canonical editable artifact when the project
+  already uses Mermaid-as-source.
+- Prefer improving diagram structure and semantics before styling.
+- Preserve technical accuracy; visual polish must never remove meaningful
+  states, branches, trust boundaries, failure paths, or labels.
+- Prefer local/versioned SVG assets for repository documentation rather than
+  hotlinking externally rendered images.
+- Treat Beautiful Mermaid as optional tooling, not as an implementation,
+  verification, authority, or completion dependency.
+- Do not install `beautiful-mermaid` merely to render a documentation asset
+  when the browser editor or an already available equivalent is sufficient.
+- If automated rendering is explicitly required, evaluate the open-source
+  `beautiful-mermaid` library separately under the project's dependency and
+  authorization policies before adding it.
+
 ## External design-reference map
 
 Select references for a product problem; they do not override project tokens or semantics. Check every adoption for keyboard and focus access, contrast, reduced motion, touch behavior, bundle/runtime cost, and fallback behavior. Cursor, canvas, 3D, audio, and decorative motion are progressive enhancement only. Do not copy source or assets; check the license and current terms for each exact resource, and treat a catalog listing as no transfer of rights.
 
+- **Technical diagrams and architecture flows**: for polished Mermaid-based architecture and workflow diagrams, use [Beautiful Mermaid by Craft](https://agents.craft.do/mermaid) when relevant; preserve canonical Mermaid source, local versioned SVG assets, and do not treat presentation tooling as a mandatory protocol gate or runtime dependency.
 - **Component source and interaction inspiration**: use [21st.dev](https://21st.dev/) to study components and interactions; inspect each source, dependency, community contribution, and premium-material term before adoption.
-- **Component and motion inspiration**: use [React Bits](https://reactbits.dev/) to study component and motion behavior; distinguish public/free material from React Bits Pro and inspect each source/dependency license.
+- **React component and motion reference**: use [React Bits](https://reactbits.dev/) to discover animated React components and interaction patterns, and inspect the [React Bits source repository](https://github.com/DavidHDev/react-bits) before adopting code. Use it only when the target stack is React or when a deliberate, reviewed adaptation is appropriate. Prefer the smallest component or pattern that solves the product need; do not install or copy the entire library by default. Inspect the exact component source, transitive dependencies, license/usage terms, accessibility behavior, reduced-motion behavior, responsive behavior, and runtime cost before adoption. Adapt tokens, typography, spacing, states, semantics, and motion to the target project's design system instead of preserving React Bits defaults.
 - **Component inspiration**: use [Fancy Components](https://www.fancycomponents.dev/) to study component composition; verify its terms separately from Motion, Tailwind, shadcn, or other dependencies.
 - **Motion primitives**: use [Motion Primitives](https://motion-primitives.com/) to study discrete interaction patterns; distinguish documented open-source material from its Pro offering and verify component/dependency terms.
 - **Component and design-system research**: use [Component Gallery](https://component.gallery/) for comparison, not for license assumptions.
@@ -321,6 +351,41 @@ Select references for a product problem; they do not override project tokens or
 - **Typography discovery**: verify each [UNCUT](https://uncut.wtf/) font's author, license, weights, and hosting rights.
 - **Creative coding and WebGL**: [cables.gl](https://cables.gl/) requires a semantic fallback, pause/offscreen behavior, a performance budget, and asset/operator provenance.
 
+### React Bits — operational use for React interfaces
+
+React Bits is an optional implementation/reference source for high-finish React interfaces. It is not a required ForgeLoop tool, protocol dependency, verification dependency, or design-system replacement.
+
+Use it when:
+
+- the target application uses React;
+- a concrete interaction, text treatment, background, reveal, or UI component would materially improve the product experience;
+- implementing the behavior from scratch would add unnecessary design or engineering cost;
+- the effect fits the selected motion intensity and visual direction.
+
+Do not use it when:
+
+- the target is not React and adaptation would add more complexity than value;
+- the component exists only as decoration without a product or communication purpose;
+- the same result already exists in the target project's design system;
+- the component violates the project's accessibility, performance, security, dependency, or browser-support constraints;
+- a static or simpler CSS/HTML implementation communicates the same result more clearly.
+
+Adoption workflow:
+
+1. **Define the need first.** Identify the concrete UI or communication problem before browsing components.
+2. **Confirm the target stack.** Verify React version, styling strategy, TypeScript/JavaScript choice, SSR/CSR boundary, and existing animation/runtime libraries.
+3. **Inspect the source.** Review the exact component in the [React Bits repository](https://github.com/DavidHDev/react-bits), not only the visual demo.
+4. **Check usage terms.** Verify the current license and any component-specific dependency or attribution requirements before copying or installing code.
+5. **Choose the smallest variant.** Prefer one component/pattern and the variant matching the project (JS/TS and CSS/Tailwind); do not add unrelated components.
+6. **Prefer local adaptation.** Adapt the component into the target project's component structure and semantic tokens rather than importing a visual identity wholesale.
+7. **Preserve semantics.** Text, controls, navigation, forms, focus states, errors, status information, and primary actions must remain semantic and usable without decorative motion.
+8. **Respect reduced motion.** Provide a static or substantially reduced alternative under `prefers-reduced-motion`; essential information must never depend on animation.
+9. **Bound runtime cost.** Lazy-load expensive effects when practical, pause continuous animation outside the viewport or on hidden pages, and avoid adding duplicate animation/runtime libraries without justification.
+10. **Verify the result.** Test keyboard/focus behavior, contrast, 320 CSS px reflow, touch behavior, reduced motion, console/runtime errors, and the project's performance budget.
+11. **Record provenance.** When code or a material implementation pattern is adopted, record React Bits as an external source in the task/project attribution or source record when applicable.
+
+ForgeLoop runtime must not gain a dependency on React Bits as a result of this guidance. Any installation belongs to the target project and remains subject to normal authorization and dependency policy.
+
 ---
 
 ## UX, Accessibility, and Quality
@@ -514,3 +579,4 @@ Select references for a product problem; they do not override project tokens or
   - Rights: the gallery's images and works are distinct from external resources it merely indexes. Consult the [terms](https://liquidglassdesign.com/terms); do not rehost, redistribute, or directly use images or works commercially without permission. For each external prompt or code resource, verify its license, provenance, credits, compatibility, and maintenance individually before use; being indexed does not transfer rights.
 - Apple — Adopting Liquid Glass (official guidance for Apple platforms): https://developer.apple.com/documentation/TechnologyOverviews/adopting-liquid-glass
 - Liquid Glass React, SVG, and Studio (experimental implementations; assess license, compatibility, weight, and maintenance): https://github.com/rdev/liquid-glass-react | https://github.com/shuding/liquid-glass | https://github.com/iyinchao/liquid-glass-studio
+- Beautiful Mermaid (technical diagram design and rendering): https://agents.craft.do/mermaid | https://agents.craft.do/mermaid/editor | https://github.com/lukilabs/beautiful-mermaid

package/ENG/documentation-quality-eng.md

@@ -0,0 +1,400 @@
+---
+name: documentation-quality-eng
+language: en
+description: "Quality standards for accurate, task-oriented, maintainable, accessible, and verifiable technical documentation."
+version: "2026.09"
+last-reviewed: "2026-08-17"
+guide-id: documentation
+---
+
+# Documentation Quality for AI Agents
+
+> **Related documents**: use [`clean-code-eng.md`](./clean-code-eng.md) when software behavior or code structure changes; [`test-code-eng.md`](./test-code-eng.md) for executable examples and verification strategy; [`sec-code-eng.md`](./sec-code-eng.md) for secrets, authentication, authorization, privacy, and sensitive examples; [`accessibility-eng.md`](./accessibility-eng.md) when a published documentation surface has additional accessibility requirements. This guide owns documentation architecture, factual quality, freshness, maintainability, and reader usability.
+>
+> **Tooling policy**: identify the documentation surface, canonical sources, and existing project checks first. Prefer already available project-native tools. Ask for authorization before installing tooling or changing the environment. If a required check cannot be executed, record it as blocked or `NOT_VERIFIED`; never claim it passed.
+
+## Context
+
+Technical documentation is part of the product contract. A document can compile, render, and contain no broken links while still being wrong, incomplete, difficult to use, or stale. Treat documentation changes with the same evidence discipline as executable changes: identify the reader, identify the authoritative source, make the smallest coherent change, and verify what can be observed.
+
+## Documentation quality model
+
+Review documentation across independent dimensions:
+
+- **Accuracy** — facts match the implementation, public contract, schema, registry, configuration, or other authoritative source.
+- **Completeness** — the intended reader has enough information to complete the intended task.
+- **Consistency** — terminology, values, commands, and behavior do not contradict other authoritative documentation.
+- **Precision** — statements are specific enough to act on and verify.
+- **Usefulness** — the content serves a real reader need rather than filling a template.
+- **Freshness** — current supported behavior is documented and obsolete claims are removed or versioned.
+- **Findability** — readers can reach the content through predictable navigation and descriptive headings/links.
+- **Accessibility** — structure and meaning remain usable with assistive technology and without visual-only cues.
+- **Verifiability** — executable or machine-defined claims are checked against authoritative sources where feasible.
+- **Flow** — prerequisites, actions, results, and recovery guidance follow the reader's task without unrelated detours.
+
+Functional correctness is required before polish. A beautiful document that is inaccurate is not high-quality documentation.
+
+## Identify the reader and job
+
+Before writing, answer:
+
+- Who is the intended reader?
+- What are they trying to accomplish or understand?
+- What can they reasonably be expected to know?
+- What prerequisites must exist?
+- What is the expected result?
+- Which project source owns each factual claim?
+- Which checks can verify the result?
+
+Do not write from memory when the repository contains a more authoritative source.
+
+## Documentation modes
+
+Use the Diátaxis model as a practical mental model. Do not create empty structures merely to satisfy it.
+
+### Tutorial
+
+Use a tutorial for learning. Provide a controlled, safe path that produces a working result and helps the reader acquire familiarity. Keep optional branches and exhaustive reference material out of the main learning flow.
+
+### How-to guide
+
+Use a how-to guide for a real task. State the goal and prerequisites, provide ordered actions, show the expected result, and include verification or recovery where useful. Link to explanation rather than interrupting the procedure with long conceptual digressions.
+
+### Reference
+
+Use reference for authoritative technical facts: APIs, CLI commands, configuration, schemas, environment variables, statuses, and error codes. Prioritize accuracy, completeness, precision, neutrality, and predictable structure. Where possible, structure reference documentation to reflect the structure of the system it describes.
+
+### Explanation
+
+Use explanation for understanding: architecture, concepts, trade-offs, context, and why the system behaves as it does. Keep required operational steps in how-to material.
+
+## README quality
+
+A repository README should normally make it possible to answer:
+
+1. What is this project?
+2. Why would I use it?
+3. What are the prerequisites?
+4. How do I get a minimal working result?
+5. Where is deeper documentation?
+6. How do I get help or contribute when relevant?
+7. What license or support policy applies?
+
+Keep the README as an entry point. Move deep tutorials, reference, architecture, and troubleshooting to dedicated documents when they grow.
+
+## Canonical sources and docs-as-code
+
+Prefer one authoritative source for machine-defined facts.
+
+Examples:
+
+```text
+package scripts       -> documented development commands
+CLI registry          -> CLI reference
+OpenAPI description   -> HTTP API reference
+JSON Schema/types     -> configuration/reference fields
+error registry        -> error-code reference
+runtime config        -> environment-variable reference
+protocol constants    -> lifecycle/status reference
+```
+
+Generate or validate projections when practical. Do not manually copy the same factual table into multiple documents.
+
+## Generated and handwritten documentation
+
+Generated content must have an explicit owner and deterministic generation path. Edit the canonical source or generator, not the generated projection.
+
+Keep handwritten content for reader context, explanation, examples, and guidance that cannot be mechanically derived.
+
+If generated regions use markers, validation must fail closed on missing, duplicate, nested, malformed, or unknown regions rather than silently rewriting arbitrary content.
+
+## Documentation impact analysis
+
+For each task, assess whether it changes:
+
+- public behavior;
+- API or CLI syntax;
+- installation or prerequisites;
+- configuration or environment variables;
+- architecture or trust boundaries;
+- authentication or authorization;
+- errors or observable states;
+- deployment or operation;
+- version compatibility;
+- deprecations or migration steps;
+- examples or workflows.
+
+Update affected documentation in the same task when the change is required for correct use.
+
+## Freshness and timeless wording
+
+Avoid time-sensitive words such as `new`, `currently`, `latest`, `now`, or `soon` in evergreen technical documentation when they will age without adding information.
+
+Use explicit versions or dates when history or compatibility requires them.
+
+Release notes, migration histories, and announcements may intentionally use time-based language.
+
+## Writing style and terminology
+
+- Use direct, concise language.
+- Prefer active voice.
+- Use second person where it clarifies reader actions.
+- Prefer specific nouns and verbs over vague references.
+- Use one canonical term per concept.
+- Define acronyms when the intended audience may not know them.
+- Use sentence-case headings unless project style requires otherwise.
+- Avoid idioms, culture-specific jokes, unnecessary metaphors, and ambiguous language in globally consumed documentation.
+- Use normative `MUST`, `SHOULD`, and `MAY` only when the document is truly specifying requirement levels.
+
+## Procedures
+
+A procedure should normally include:
+
+```text
+goal
+prerequisites
+ordered actions
+expected result
+verification
+recovery/troubleshooting
+```
+
+Use numbered steps when order matters and imperative verbs for required actions.
+
+Do not hide a prerequisite after the step that depends on it.
+
+## Commands and code samples
+
+Runnable commands and copyable code must be safe and credible.
+
+- Validate examples when feasible.
+- Never invent successful command output.
+- Label illustrative output explicitly.
+- Use clear placeholders.
+- Never include real secrets, tokens, private keys, PII, or production credentials.
+- Explain destructive effects before the command.
+- Follow the project's language and formatting conventions.
+- Prefer real text over screenshots of terminal output or code.
+
+## API documentation
+
+For HTTP APIs, use a machine-readable description such as OpenAPI when the project already supports or benefits from it.
+
+Document relevant:
+
+- authentication and authorization;
+- operations and paths;
+- parameters;
+- request and response bodies;
+- status codes and errors;
+- pagination;
+- rate limits;
+- idempotency;
+- webhooks;
+- versioning;
+- deprecation;
+- examples.
+
+Do not require OpenAPI for projects without an HTTP API.
+
+## CLI documentation
+
+CLI reference should describe relevant:
+
+- usage;
+- commands;
+- arguments;
+- options;
+- aliases;
+- defaults;
+- repeatable options;
+- exit/error behavior;
+- examples;
+- shell-sensitive behavior;
+- configuration precedence.
+
+Derive or validate these facts from the CLI registry/parser when possible.
+
+## Configuration and environment documentation
+
+Document each public configuration item with relevant:
+
+```text
+name
+purpose
+type
+required/optional
+default
+allowed values
+safe example
+secret classification
+scope
+precedence
+reload/restart behavior
+```
+
+Keep `.env.example`, runtime configuration, and documentation consistent.
+
+## Architecture documentation
+
+Document the architecture at the smallest useful level.
+
+Cover relevant:
+
+- system context;
+- major runtime boundaries;
+- dependencies;
+- data flow;
+- trust boundaries;
+- storage;
+- external systems;
+- deployment topology;
+- important architectural decisions.
+
+Use diagrams only when they improve understanding. A context/container view is enough for many systems; do not generate every possible diagram level.
+
+For significant decisions, use an ADR or equivalent record containing context, decision, alternatives when useful, consequences, and status.
+
+## Troubleshooting and runbooks
+
+Write troubleshooting around observable symptoms or stable error codes.
+
+Prefer:
+
+```text
+symptom
+likely cause
+how to verify
+correction
+next diagnostic/escalation step
+```
+
+Operational runbooks should identify trigger, access prerequisites, safety checks, steps, verification, rollback, and escalation.
+
+## Accessibility
+
+- Use one clear title.
+- Maintain meaningful heading hierarchy.
+- Use descriptive link text instead of `click here`.
+- Provide text alternatives for informative images.
+- Do not put unique information only in screenshots or diagrams.
+- Do not use color, location, shape, or direction as the only semantic cue.
+- Use tables for tabular data, not layout.
+- Keep long content scannable.
+- Prefer real text for code and terminal output.
+
+## Security and sensitive information
+
+Documentation must not expose:
+
+```text
+tokens
+passwords
+private keys
+real credentials
+session identifiers
+personal data
+production connection strings
+internal secrets
+```
+
+Use explicitly fake examples. Authentication and authorization documentation must match actual server-side behavior and permissions.
+
+## Versioning, deprecation, and migration
+
+If the project has a versioned public API, keep its documentation precise and comprehensive enough to understand compatibility.
+
+Document breaking changes and deprecations. When users need action to upgrade, provide a migration guide with affected versions, prerequisites, steps, verification, rollback/recovery, and known incompatibilities.
+
+Do not promise removal dates or future behavior unless the project has committed to them.
+
+## Validation and evidence
+
+Use the project's own tools first.
+
+Possible checks include:
+
+- Markdown lint/validation;
+- internal link and anchor validation;
+- external link checks with an explicit network-failure policy;
+- documentation build;
+- code example execution or compilation;
+- OpenAPI/schema validation;
+- CLI/reference parity;
+- configuration/reference parity;
+- generated-document freshness;
+- diagram source/artifact parity;
+- README quick-start execution.
+
+Do not install optional tooling solely to satisfy this list.
+
+If a required check is unavailable, record it as blocked or `NOT_VERIFIED`. Never report an unexecuted check as passed.
+
+## Anti-patterns
+
+Avoid:
+
+- README as a dumping ground;
+- tutorials mixed with exhaustive reference;
+- procedures interrupted by unrelated explanation;
+- factual tables manually duplicated across files;
+- untested commands presented as guaranteed;
+- invented output;
+- screenshots of code or terminal text;
+- stale time-sensitive wording;
+- dead-end documents with no navigation;
+- manual edits to generated documentation;
+- undocumented breaking changes;
+- known required documentation deferred indefinitely after behavior changes.
+
+## Agent workflow
+
+For documentation work:
+
+1. Discover relevant documentation and project truth sources.
+2. Classify the reader need: tutorial, how-to, reference, or explanation.
+3. Identify the authoritative source for factual claims.
+4. Map documentation impact.
+5. Make the smallest coherent update.
+6. Run relevant project-native documentation checks.
+7. Inspect the diff from the intended reader's perspective.
+8. Cross-check facts against implementation or canonical machine sources.
+9. Record observed verification evidence through the project/ForgeLoop verification flow.
+10. Do not claim completion beyond the evidence.
+
+## Documentation Definition of Done
+
+Before completion verify:
+
+- [ ] Intended reader and purpose are clear.
+- [ ] Factual claims match authoritative project sources.
+- [ ] The documentation mode fits the reader need.
+- [ ] Required information is complete for the intended task.
+- [ ] Terminology is consistent.
+- [ ] Procedures are ordered and actionable.
+- [ ] Examples and commands are safe and validated when feasible.
+- [ ] Internal navigation and links are coherent.
+- [ ] Accessibility basics are satisfied.
+- [ ] No real secrets or sensitive data appear.
+- [ ] Generated/reference material is fresh.
+- [ ] Version/deprecation/migration impact is documented when applicable.
+- [ ] Relevant project-native checks have observed evidence.
+- [ ] Unavailable required checks are explicitly `NOT_VERIFIED` or blocked.
+- [ ] The completion claim does not exceed the evidence.
+
+## Sources and further reading
+
+This guide is an original operational synthesis informed by:
+
+- Diátaxis — https://diataxis.fr/
+- Diátaxis quality — https://diataxis.fr/quality/
+- Google Developer Documentation Style Guide — https://developers.google.com/style
+- Google accessible documentation guidance — https://developers.google.com/style/accessibility
+- Google code sample guidance — https://developers.google.com/style/code-samples
+- Google timeless documentation guidance — https://developers.google.com/style/timeless-documentation
+- GitHub repository documentation guidance — https://docs.github.com/en/repositories/creating-and-managing-repositories/best-practices-for-repositories
+- W3C WAI writing guidance — https://www.w3.org/WAI/tips/writing/
+- OpenAPI Specification — https://spec.openapis.org/oas/
+- Semantic Versioning — https://semver.org/
+- C4 model — https://c4model.com/
+- RFC 2119 — https://www.rfc-editor.org/rfc/rfc2119.html

package/ENG/taste-frontend-eng.md

@@ -3,7 +3,7 @@ name: taste-frontend-eng
 language: en
 description: "Contextual visual-taste review for premium frontend and brand-heavy work."
 version: "2026.09"
-last-reviewed: "2026-08-10"
+last-reviewed: "2026-08-17"
 guide-id: taste
 ---
 
@@ -107,8 +107,11 @@ Use the existing product system when one is present. If the target has no
 system, choose a small coherent set of semantic tokens, components, states,
 and usage rules that the team can maintain. A vendor guide, gallery, template,
 or AI output can inform a direction, but it is not evidence of product fit,
-license, accessibility, or performance. Keep any external reference in the
-task's source and attribution records; do not add a network dependency to
+license, accessibility, or performance. For React-specific external component
+or motion references, follow the React Bits adoption rules in
+[`design-code-eng.md`](./design-code-eng.md) rather than treating a gallery
+component as a project design-system default. Keep any external reference in
+the task's source and attribution records; do not add a network dependency to
 ForgeLoop runtime.
 
 ## Visual Pre-Flight