@cassiomc1/forgeloop 0.1.0

package/README.md

@@ -0,0 +1,492 @@
+# ForgeLoop — Instruction Guides for AI Agents
+
+[![Docs quality](https://github.com/cassiomc1/mdfiles/actions/workflows/docs-quality.yml/badge.svg?branch=main)](https://github.com/cassiomc1/mdfiles/actions/workflows/docs-quality.yml)
+
+An English-only collection of operational guides for AI agents and developers.
+It covers product strategy, code, testing, security, performance,
+accessibility, design, and web games across web, mobile, and desktop projects.
+
+The files are Markdown and can be used as references, as a foundation for
+`AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, and
+`.github/copilot-instructions.md`. The supported-agent contract is documented
+in [`AGENT_COMPATIBILITY.md`](./AGENT_COMPATIBILITY.md). Adopt only the guides
+relevant to the target project.
+
+ForgeLoop is the portable, evidence-first loop that connects deterministic
+routing, checkpointed state, observable evidence, conformance, and delegation
+for compatible agent harnesses.
+
+## Catalog
+
+| Topic | When to use it | Guide |
+| --- | --- | --- |
+| Premium websites | End-to-end process from strategy to launch | [`premium-sites-studio-eng.md`](./ENG/premium-sites-studio-eng.md) |
+| Clean code | Readable, observable, secure, and operable code | [`clean-code-eng.md`](./ENG/clean-code-eng.md) |
+| Testing | Risk-based testing strategy | [`test-code-eng.md`](./ENG/test-code-eng.md) |
+| Security | Web, mobile, desktop, APIs, and supply chain | [`sec-code-eng.md`](./ENG/sec-code-eng.md) |
+| Design | Visual direction, UX, motion, and perceived performance | [`design-code-eng.md`](./ENG/design-code-eng.md) |
+| Performance | Measurement, diagnosis, budgets, and optimization | [`perf-code-eng.md`](./ENG/perf-code-eng.md) |
+| Accessibility | WCAG 2.2-oriented protocol for interfaces | [`accessibility-eng.md`](./ENG/accessibility-eng.md) |
+| Web games | Architecture, design, and operation of 2D, 3D, and procedural games | [`games-code-design-web-eng.md`](./ENG/games-code-design-web-eng.md) |
+
+Each guide declares its name, `language: en`, description, version, and review
+date in frontmatter. The repository validator checks that the guide metadata
+and catalog remain synchronized.
+
+## Universal project loop
+
+The kit turns each request into a verifiable cycle: discover the project,
+define an execution contract, select applicable guides, execute, verify,
+diagnose, and correct until success or a genuine external blocker.
+[`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) is the operational source;
+[`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) prevents irrelevant context from being
+loaded; and [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) preserves only durable,
+proven project facts.
+
+The canonical system map, including the routing/state/evidence architecture, is
+in [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md).
+
+```mermaid
+flowchart TB
+  root["FORGELOOP"]
+
+  subgraph surfaces["CONTROL SURFACES"]
+    direction LR
+    routing["ROUTING"] --> routingFacts["deterministic<br/>decisions"]
+    state["STATE"] --> checkpoint["checkpoint<br/>facts"]
+    evidence["EVIDENCE"] --> claims["observable<br/>claims"]
+
+    checkpoint --> repository["repository"]
+    checkpoint --> contract["contract"]
+    repository --> freshness["freshness"]
+    contract --> freshness
+  end
+
+  root --> routing
+  root --> state
+  root --> evidence
+
+  routingFacts --> conformance["CONFORMANCE"]
+  routingFacts --> delegation["DELEGATION"]
+  freshness --> conformance
+  freshness --> delegation
+  claims --> conformance
+  claims --> delegation
+
+  conformance --> verdict["VALID / STALE / INVALID"]
+  delegation --> verdict
+  verdict --> harness["compatible harness"]
+
+  classDef root fill:#08090C,stroke:#6E6AF5,stroke-width:3px,color:#EDEEF0;
+  classDef routing fill:#4F46E5,stroke:#A5B4FC,stroke-width:2px,color:#FFFFFF;
+  classDef state fill:#373A46,stroke:#A1A1AA,stroke-width:2px,color:#FFFFFF;
+  classDef evidence fill:#3EDBB8,stroke:#99F6E4,stroke-width:2px,color:#08090C;
+  classDef fact fill:#181B24,stroke:#6E6AF5,stroke-width:1px,color:#EDEEF0;
+  classDef support fill:#181B24,stroke:#8A8F98,stroke-width:1px,color:#EDEEF0;
+  classDef gate fill:#3730A3,stroke:#A5B4FC,stroke-width:2px,color:#FFFFFF;
+  classDef result fill:#C9A876,stroke:#F5D9A6,stroke-width:2px,color:#08090C;
+  classDef harness fill:#101218,stroke:#3EDBB8,stroke-width:2px,color:#EDEEF0;
+
+  class root root;
+  class routing,routingFacts routing;
+  class state,checkpoint state;
+  class evidence,claims evidence;
+  class repository,contract,freshness fact;
+  class conformance,delegation gate;
+  class verdict result;
+  class harness harness;
+  style surfaces fill:#101218,stroke:#2D3340,stroke-width:1px,color:#EDEEF0;
+  linkStyle default stroke:#8A8F98,stroke-width:1.5px;
+```
+
+Equivalent reading for text-only environments: ForgeLoop turns routing into
+deterministic decisions, state into checkpoint facts, and evidence into
+observable claims. Repository and contract facts establish freshness; all
+three control surfaces feed conformance and delegation, which produce a
+`VALID`, `STALE`, or `INVALID` result for the compatible harness.
+
+The operational request loop remains:
+
+```text
+Request → discovery → profile → routing → plan → execution
+        → verification → correction when needed → final evidence
+```
+
+Thin native adapters support Codex, Claude Code, Cursor, and GitHub Copilot.
+Antigravity, OpenCode, Hermes, Pi, Command Code, and Freebuff use the shared
+`AGENTS.md` entry point. All ten agents delegate to the same canonical
+documents; see [`AGENT_COMPATIBILITY.md`](./AGENT_COMPATIBILITY.md) for the
+official sources and precedence notes.
+
+### Use with npm
+
+The npm CLI targets Node.js 20 or newer and installs the kit into an existing
+project without overwriting local instructions. When the package is available
+in the npm registry, use the commands below; otherwise use the repository
+checkout fallback.
+
+```bash
+npx @cassiomc1/forgeloop init
+npx @cassiomc1/forgeloop doctor
+npx @cassiomc1/forgeloop update
+```
+
+Protocol-support commands are local and do not invoke an agent or model:
+
+```bash
+npx @cassiomc1/forgeloop route --work complete-website --surface ui --risk untrusted-input
+npx @cassiomc1/forgeloop inspect --json
+npx @cassiomc1/forgeloop status --json
+npx @cassiomc1/forgeloop status --contract-file .forgeloop/current-contract.json --json
+npx @cassiomc1/forgeloop validate-state --json
+npx @cassiomc1/forgeloop validate-receipt --file ./execution-receipt.json --json
+npx @cassiomc1/forgeloop validate-protocol --route-file ./routing-result.json --state-file .forgeloop/work-state.json --receipt-file ./execution-receipt.json --contract-file .forgeloop/current-contract.json --json
+```
+
+`route` expands declared signals into deterministic guide IDs and reason codes.
+`inspect`, `status`, and `validate-state` explain installation and resumable
+state; they do not execute commands from the target profile.
+`inspect` and `status` parse the target-local schemas and report `valid`,
+`missing`, `invalid`, or `unsupported-version` health. A status without a
+current contract file reports contract comparison as `NOT_VERIFIED` and does
+not claim full freshness. `validate-protocol` is read-only and checks
+cross-artifact relationships plus the same derived freshness classification
+used by `inspect` and `status`. Supply `--contract-file` to compare the saved
+contract fingerprint with the current contract; omitting it leaves contract
+freshness as `NOT_VERIFIED` and a complete artifact set requires revalidation.
+It returns `VALID`, `INCOMPLETE`, `STALE`, `INCONSISTENT`, or `INVALID` with
+exact invariant codes and derived stale reasons. The persisted
+`.forgeloop/work-state.json` schema is unchanged: `status`, `stale`, and `fresh`
+are never stored in that file. Status precedence is `INVALID` > `INCONSISTENT`
+> `STALE` > `INCOMPLETE` > `VALID`.
+All protocol-support commands are local and offline-capable by default; the
+package sends no telemetry and has no central trace service.
+Capability gaps and inline/non-Git degraded mode are defined in
+[`AGENT_COMPATIBILITY.md`](./AGENT_COMPATIBILITY.md); they are reported as
+limitations rather than treated as silent successes.
+
+### Protocol compatibility
+
+The npm package version is independent of protocol version. The current
+serializable artifact contract is `schemaVersion: 1` and `protocolVersion: 1`.
+
+- Patch releases preserve the v1 schemas, enums, transitions, and existing
+  command contracts while correcting implementation defects.
+- Minor releases preserve existing v1 artifacts and commands; they may add
+  documentation, new commands, new guide IDs, or a new explicitly named
+  schema. Existing consumers must still reject unknown fields rather than
+  silently treating an unrecognized artifact as valid.
+- Major releases may change required fields, enums, transitions, or safety
+  semantics and must document migration requirements together with a protocol
+  version change.
+
+The compatibility fixture in
+[`tests/fixtures/compatibility/protocol-v1.json`](./tests/fixtures/compatibility/protocol-v1.json)
+is a small conformance marker, not a runtime configuration file.
+
+### CLI security and trust boundaries
+
+The CLI is a local validator and installer. It does not execute instructions,
+profile commands, receipt data, state data, or hidden prompts supplied by a
+target project. Its main threat boundaries are:
+
+| Threat | Mitigation or accepted limit |
+| --- | --- |
+| Path traversal and symlink escape | Target and managed paths use safe-path and realpath containment checks; a symlinked target or escaped child is rejected. |
+| Manifest tampering | Managed-file hashes and manifest shape are checked by `doctor`; discrepancies become findings rather than silent overwrites. |
+| Untrusted state or profile data | JSON schemas, semantic checks, secret-like field checks, and non-execution rules apply before state or profile data is used. |
+| Command injection | Git inspection uses fixed arguments without a shell; the CLI never treats project text as a command. |
+| Data exposure | Receipts and checkpoints reject secret-like keys and values; examples use placeholders, and the repository secret scanner runs in CI. |
+| Unsafe update overwrite | `update` preserves locally modified files and `PROJECT_PROFILE.md`; adoption and writes remain bounded to the selected target. |
+| Dependency supply chain | Runtime code uses Node built-ins only; the package does not install agents, providers, plugins, or remote services. |
+| Stale replay | Work state records contract and repository fingerprints; drift requires revalidation and never reruns destructive or publication actions automatically. |
+| Unverified publication | Receipts carry explicit publication booleans; local success never implies a push, pull request, merge, release, or deployment. |
+
+The full boundary inventory, residual limitations, and executable evidence are
+in [`THREAT_MODEL.md`](./THREAT_MODEL.md).
+
+The CLI cannot protect a target from a separately privileged or hostile process
+that changes the filesystem after validation. Consumers must still review
+permissions, package provenance, and external actions before granting authority.
+
+From a repository checkout before npm publication, run the same commands with
+Node directly:
+
+```bash
+node src/cli.js init
+node src/cli.js doctor
+node src/cli.js update
+```
+
+The release workflow uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers)
+through GitHub Actions OIDC. Before the first release, register this repository
+and workflow as the package's trusted publisher in npm; each `vX.Y.Z` tag must
+match `package.json`. After publishing, verify the package version and its npm
+provenance record.
+
+The commands above use the current directory. To install into another existing
+project directory, pass a relative or absolute `--path`:
+
+```bash
+# Existing project relative to the current directory
+npx @cassiomc1/forgeloop init --path ./my-project
+npx @cassiomc1/forgeloop doctor --path ./my-project
+npx @cassiomc1/forgeloop update --path ./my-project
+
+# Existing project at an absolute path
+npx @cassiomc1/forgeloop init --path /path/to/my-project
+npx @cassiomc1/forgeloop doctor --path /path/to/my-project
+npx @cassiomc1/forgeloop update --path /path/to/my-project
+```
+
+The target must already exist and be a directory; the CLI will not create or
+replace an arbitrary path. Use `--dry-run` to preview writes before `init` or
+`update`. `--json`, `--strict`, and `--adopt <path>` are supported by `doctor`;
+adoption is limited to a supported adapter that has been reviewed locally. The
+CLI records managed files and their hashes in `.forgeloop/manifest.json`; `update`
+leaves locally modified files and `PROJECT_PROFILE.md` untouched. If a target
+already has a manifest, rerun `update` instead of `init`. Symlinked targets or
+template parents are rejected, and unadopted pre-existing adapters are reported
+for manual merge with the loop reference.
+
+### Migrate an existing mdfiles installation
+
+The ForgeLoop rename changes the target metadata namespace. From the existing
+project root, move the directory manually and refresh its manifest:
+
+```bash
+mv .mdfiles .forgeloop
+npx @cassiomc1/forgeloop update
+```
+
+ForgeLoop does not automatically migrate, dual-write, or delete a legacy
+`.mdfiles` directory. The serialized contract remains `schemaVersion: 1` and
+`protocolVersion: 1`; only the package, CLI, and target namespace change.
+
+### Install in a target project
+
+If npm is unavailable, download this public repository as a ZIP or clone it
+into a temporary directory. Copy this structure to the target project's root
+while preserving relative paths:
+
+```text
+AGENTS.md
+CLAUDE.md
+AGENT_COMPATIBILITY.md
+LOOP_ENGINEERING.md
+GUIDE_ROUTER.md
+PROJECT_PROFILE.md
+LOOP_SYSTEM_DESIGN.md
+QUALITY_SCORECARD.md
+TERMINOLOGY.md
+EXECUTION_STATE.md
+DELEGATION_PROTOCOL.md
+ORCHESTRATOR_INTEGRATION.md
+THREAT_MODEL.md
+CONTRACT_COVERAGE.md
+THIRD_PARTY_NOTICES.md
+LICENSE
+LICENSE-DOCS.md
+.forgeloop/.gitignore
+.github/copilot-instructions.md
+.cursor/rules/project-loop.mdc
+ENG/
+schemas/
+```
+
+If the target already has `AGENTS.md`, `CLAUDE.md`, Copilot instructions, or
+Cursor rules, merge only the adapter block that points to the loop. Never
+overwrite specific local instructions. The `scripts/`, `.github/workflows/`,
+and quality configuration files are optional for kit consumers but required to
+maintain and validate this source repository.
+
+### First run
+
+On the first task in a target project with code or manifests, change
+`profile-mode` from `template` to `project`, discover the stack, and record only
+confirmed facts in `PROJECT_PROFILE.md`. Keep `language: en`.
+
+The profile must not store tokens, passwords, keys, credentials, or task logs.
+Unknown commands remain unverified until a real source identifies them.
+
+To confirm activation before the first implementation, ask the agent:
+
+```text
+Before implementing, report the confirmed project profile, the guide IDs
+selected through GUIDE_ROUTER.md, and the checks you will use. Do not change
+files yet.
+```
+
+A useful response cites profile evidence, selected guide IDs, and real project
+commands. A generic response that does not mention the loop, router, or sources
+indicates that the adapter was not loaded.
+
+After installation, start the preferred agent from the target project
+directory. Use `AGENT_COMPATIBILITY.md` to confirm which file it should load and
+which native entry point is expected. A live agent session is not required for
+package installation or its automated tests.
+
+### Update the kit
+
+When adopting a newer version, preserve target-specific facts from
+`PROJECT_PROFILE.md`. Compare adapters before replacing them, update the loop,
+router, notices, and guides as one coherent set, and never erase local
+instructions. If validators were copied, run:
+
+```bash
+python3 scripts/validate_loop_system.py --self-test
+python3 scripts/validate_loop_system.py
+python3 scripts/scan_secrets.py
+```
+
+When maintaining a checkout of this source repository, run the npm package
+checks as well:
+
+```bash
+npm test
+npm run pack:check
+```
+
+Architecture and boundaries are documented in
+[`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md).
+
+## Tool approval policy
+
+Identify the stack, current stage, and applicable checks. Prefer an equivalent
+tool already available when it produces compatible evidence. The task-scoped
+Qwen-MM-Plugins installation described below is the narrow capability exception
+when a required capability is missing; system tools, credentials, and unrelated
+environment changes remain subject to their normal host controls. If a required
+check cannot run and no safe alternative exists, record the blocker and do not
+claim that the check passed. Unrelated optional references must never be
+installed automatically.
+
+## Optional multimodal capabilities
+
+[Qwen-MM-Plugins](https://github.com/QwenLM/Qwen-MM-Plugins) can extend a
+supported agent harness with skills and optional MCP servers. Before using a
+multimodal or media operation, the agent checks the model and harness for a
+callable native capability. If the task requires a missing keyless capability,
+the agent installs only the smallest matching `qwen-mm-plugins-<cap>` capability
+and verifies that it is callable before continuing; it does not install every
+capability at startup.
+
+No API key is used by default for native image, video, or document reading.
+Optional provider-backed operations follow this boundary:
+
+| Capability or operation | Configuration required |
+| --- | --- |
+| Native image, video, and document reading | No API key; video/audio workflows may need `ffmpeg` and other documented system tools |
+| Vision chat, OCR, grounding, audio transcription, Omni audio-video understanding, generation, and video-memory construction | `DASHSCOPE_API_KEY` |
+| Web search, web extraction, and image search | `SERPER_API_KEY` |
+| Segmentation through a SAM3 service | `SAM3_SERVER_URL` |
+| Blender, FreeCAD, Office, browser-backed visualization, and `edu-agent` workflows | The selected application's system dependencies and upstream configuration; `edu-agent` TTS requires `DASHSCOPE_API_KEY` |
+
+Provide optional credentials through the process environment or the official
+Qwen configuration file at `~/.qwen-mm-plugins/config` (or its documented
+override). Never put keys in Git, `PROJECT_PROFILE.md`, or copied instruction
+files. The agent must leave an API-backed capability disabled when its key or
+service endpoint is absent, and report missing system dependencies instead of
+claiming that the feature is available.
+
+Use the upstream [installation guide](https://github.com/QwenLM/Qwen-MM-Plugins/blob/main/docs/en/installation.md)
+for the active harness's current install and verification commands, supported
+capabilities, system dependencies, and Windows/WSL2 constraints. This project
+does not vendor Qwen code, add it to the npm package, or install it through
+`forgeloop init`, `update`, or `doctor`.
+
+## HyperFrames for video and motion
+
+[HyperFrames](https://hyperframes.heygen.com) is an option for deterministic
+HTML, CSS, and JavaScript-based trailers, demos, presentations, and motion
+graphics. It complements the design, accessibility, performance, and testing
+guides; it does not replace those checks. Review the
+[quickstart](https://hyperframes.heygen.com/quickstart) and
+[CLI documentation](https://hyperframes.heygen.com/packages/cli) before
+adoption. Local rendering requires Node.js 22+ and FFmpeg.
+
+## Structure
+
+```text
+.
+├── AGENTS.md                       # shared Codex-compatible entry point
+├── CLAUDE.md                       # Claude Code entry point
+├── AGENT_COMPATIBILITY.md          # supported agents and official sources
+├── LOOP_ENGINEERING.md             # canonical operating cycle
+├── GUIDE_ROUTER.md                 # contextual guide selection
+├── PROJECT_PROFILE.md              # verified project facts
+├── LOOP_SYSTEM_DESIGN.md           # architecture and boundaries
+├── THIRD_PARTY_NOTICES.md          # provenance and rights
+├── LICENSE                         # CLI and validator code license
+├── LICENSE-DOCS.md                 # original documentation license boundary
+├── ENG/                            # eight English guides
+├── .cursor/rules/                  # always-active Cursor rule
+├── .github/copilot-instructions.md # GitHub Copilot entry point
+├── .github/workflows/              # quality automation
+├── scripts/                        # structural, language, and secret checks
+├── tests/                          # validator regression tests
+├── src/                            # npm CLI implementation
+├── .gitignore                      # ignored local files
+├── .lychee.toml                    # link-check configuration
+├── .markdownlint-cli2.jsonc        # Markdown rules
+└── README.md
+```
+
+## Maintenance
+
+- Preserve guide requirements, exceptions, numbers, examples, and references when editing.
+- Update `version` and `last-reviewed` when a guide's normative content changes.
+- Verify that relative links remain inside the repository.
+- Keep root instructions, comments, examples, fixtures, and guide content in English.
+- Keep `THIRD_PARTY_NOTICES.md` with every distributed copy of the kit.
+
+### Workflow quality gates
+
+For non-trivial behavior changes, use the proportional design, plan, test, and
+review gates in [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md). Keep adapters
+and entry-point instructions thin so the canonical workflow stays in one place.
+
+### Local checks
+
+First check whether the Markdown linter is already installed:
+
+```bash
+command -v markdownlint-cli2
+```
+
+When it is available, run it directly without downloading anything:
+
+```bash
+markdownlint-cli2
+```
+
+If it is missing, request approval before running this pinned one-off download:
+
+```bash
+npx --yes markdownlint-cli2@0.23.2
+```
+
+In a checkout of this source repository, run the repository validators with
+Python's standard library:
+
+```bash
+python3 scripts/validate_loop_system.py --self-test
+python3 scripts/validate_loop_system.py
+python3 scripts/validate_markdown.py --self-test
+python3 scripts/validate_markdown.py
+python3 -m unittest discover -s tests -v
+python3 scripts/scan_secrets.py
+```
+
+The [Docs quality workflow](./.github/workflows/docs-quality.yml) also checks
+Markdown, links, frontmatter, unique names, code fences, relative links,
+adapters, the guide catalog, routing scenarios, and secret-shaped values on
+pushes and pull requests.
+
+## Rights and provenance
+
+The CLI and validator code use the MIT text in [`LICENSE`](./LICENSE). Original
+documentation uses CC BY 4.0 as described in [`LICENSE-DOCS.md`](./LICENSE-DOCS.md),
+and adapted or externally sourced material remains subject to the conditions in
+[`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md). The npm `license` field
+points to the code license; it does not relicense the bundled documentation.

package/TERMINOLOGY.md

@@ -0,0 +1,21 @@
+# ForgeLoop terminology
+
+| Term | Meaning |
+| --- | --- |
+| Adapter | A thin native instruction entry file that points an agent to the canonical protocol. |
+| Guide | A focused technical Markdown document selected for a task surface or risk. |
+| Route | The deterministic guide set produced after an agent declares routing signals. |
+| Contract | The observable objective, deliverables, constraints, risks, verification, authority, and stop condition for a task. |
+| Checkpoint | A validated local snapshot of compatible work state stored under `.forgeloop`. |
+| Receipt | A structured, secret-free summary of changes, checks, review, limitations, and publication state. |
+| Review | A specification and implementation quality check performed after verification. |
+| Independent review | A review performed by an identity different from the implementer and explicitly marked independent. |
+| Blocker | A genuine condition that prevents safe progress and has a category and evidence. |
+| Capability | A model, harness, tool, or system feature required by a scoped operation. |
+| Authority | The explicit permission and target boundary for a destructive or external action. |
+| Publication | Push, pull request, merge, release, or deployment; none is implied by local success. |
+| Portable protocol | A serializable, framework-neutral contract that compatible agents can execute in their own harness. |
+| Runtime | A process that owns execution, scheduling, model calls, or persistence; `ForgeLoop` intentionally does not provide one. |
+| Evidence kind | One of `OBSERVED`, `INFERRED`, `NOT_VERIFIED`, or `BLOCKED`; evidence never upgrades an unverified claim by itself. |
+| Required artifact | A checkpoint-recorded relative path and SHA-256 hash that must still match before resume. |
+| Conformance | Relationship validation across route, state, receipt, task brief, and delegated-result artifacts. |

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,129 @@
+# Third-Party Notices
+
+This file records provenance and reuse boundaries for the external URLs cited
+by the README and guides. A citation is a reference, not a declaration that a
+resource is a dependency, bundled material, or available for reuse.
+
+## Collection license
+
+The CLI and validator code are licensed under the MIT License in `LICENSE`.
+Original documentation is offered under CC BY 4.0 as described in
+`LICENSE-DOCS.md`. Those notices do not apply to adapted or external material;
+review the applicable source terms before redistributing such material.
+
+## Adapted and editorial sources
+
+### A11Y.md
+
+- Project: [fecarrico/A11Y.md](https://github.com/fecarrico/A11Y.md).
+- Identified author: Felipe A. Carriço.
+- License identified by the upstream project: MIT.
+- Use in this collection: adapted accessibility guidance with attribution
+  preserved. Consult the upstream repository for its current license text and
+  conditions.
+
+### Clean Code for AI Agents
+
+- Source: [Fabio Akita's article](https://akitaonrails.com/en/2026/04/20/clean-code-for-ai-agents/).
+- Use in this collection: editorial influence for an original operational
+  synthesis about clean code for AI agents.
+- Boundary: consult the source before reusing its text or other material.
+
+## External standards and public documentation
+
+The guides cite standards and public technical documentation, including
+[W3C](https://www.w3.org/TR/), Apple, Android, Microsoft, MDN, WHATWG, IETF,
+OWASP, and Google documentation. They are technical references for
+accessibility, platform behavior, security, performance, testing, and web
+standards; their specifications, examples, names, and marks remain governed by
+the applicable source.
+
+## Software, package, and tool references
+
+The guides also cite external software, package, framework, registry, and tool
+documentation, including [HyperFrames](https://hyperframes.heygen.com/) and
+the projects referenced by the design, game, performance, security, and testing
+guides. These URLs support evaluation or implementation decisions only. Their
+inclusion does not install, bundle, or declare any project as a dependency of
+this collection. Check the specific project's current license, terms,
+dependencies, version, and distribution conditions before adoption.
+
+### Superpowers
+
+- Project: [Superpowers](https://github.com/obra/superpowers).
+- License declared by the upstream project: [MIT](https://github.com/obra/superpowers/blob/main/LICENSE).
+- Use in this collection: an editorial and process reference for approved
+  workflow boundaries and public discoverability only.
+- Boundary: this repository links to Superpowers as a reference; it is not a dependency of `ForgeLoop`, and `ForgeLoop` does not copy, bundle, install, or vendor any Superpowers source, skill, hook, plugin, runtime, dependency, credential, or provider.
+
+### Runtime and validator boundary
+
+The distributed CLI and repository validators use Node.js and Python standard
+libraries plus the JSON Schema documents shipped in this repository. No
+third-party runtime package, agent, provider, plugin, remote trace service, or
+model is bundled or installed by `ForgeLoop`. A future host that adds one of
+those capabilities must review its own license, dependency tree, credentials,
+network behavior, and distribution terms separately.
+
+## Visual, gradient, and gallery references
+
+### Canvas UI and Liquid Glass Design
+
+- References: [Canvas UI](https://canvasui.dev/) and
+  [Liquid Glass Design](https://liquidglassdesign.com/).
+- Use in this collection: visual-direction references.
+- Boundary: check the provenance, author, license, attribution, and other
+  conditions of a specific asset, image, prompt, text, code sample, or indexed
+  work before reuse.
+
+### Gradient Studio
+
+- Source: [Gradient Studio](https://gradientsaas.blogspot.com/), identified in
+  the guide as a project by Amit Gajare.
+- Use in this collection: a reference for procedural CSS, Tailwind, and SCSS
+  gradient exploration.
+- Boundary: confirm the current source terms and the provenance of any output
+  or asset before reuse.
+
+## Design reference sites
+
+The following nine sites are references in the design guide. None is a
+dependency of this collection or a blanket permission to reuse code, assets,
+fonts, templates, or other material.
+
+- [21st.dev](https://21st.dev/): component and template registry; check the
+  terms for the specific author, community contribution, or paid material.
+- [React Bits](https://reactbits.dev/): component and motion reference; keep
+  public/free material, React Bits Pro, and dependency terms separate.
+- [Fancy Components](https://www.fancycomponents.dev/): component reference;
+  verify the linked source license and each dependency before reuse.
+- [Motion Primitives](https://motion-primitives.com/): motion reference; keep
+  documented open-source material, the Pro offering, and dependency terms
+  separate.
+- [Component Gallery](https://component.gallery/): comparison catalog; the
+  design systems and examples it indexes retain their own terms.
+- [NumberFlow](https://number-flow.barvian.me/): external software reference;
+  verify the upstream license and dependency terms before adoption.
+- [Cursify](https://cursify.ui-layouts.com/): pointer-enhancement reference;
+  verify the component, source, and dependency terms before adoption.
+- [UNCUT](https://uncut.wtf/): typography-discovery catalog; a listing is not a
+  font license, so check the exact author, files, weights, hosting, and
+  redistribution rights.
+- [cables.gl](https://cables.gl/): creative-coding and WebGL reference; check
+  the tool, exported patches or operators, code, and third-party assets
+  separately before distribution.
+
+### Qwen-MM-Plugins
+
+- Project: [QwenLM/Qwen-MM-Plugins](https://github.com/QwenLM/Qwen-MM-Plugins).
+- License declared by the upstream project: [Apache-2.0](https://github.com/QwenLM/Qwen-MM-Plugins/blob/main/LICENSE).
+- Use in this collection: an optional reference for task-scoped multimodal capabilities that an active agent may install through its supported harness when a task requires them.
+- Boundary: this repository links to the project but does not copy, vendor, or relicense its source, skills, MCP servers, models, or dependencies. Verify current upstream terms, dependencies, service costs, and harness instructions before installing or redistributing anything.
+
+## Fonts, assets, and premium content
+
+Fonts named in the design guide are examples only and are not bundled by this
+collection. Do not host, redistribute, or infer rights for a font, image,
+template, prompt, audio asset, or other premium material from a citation or
+catalog listing. Verify the exact resource's author, license, attribution,
+hosting, and current terms before use.