@starci/skills 1.1.0

package/alias/INDEX.vi.md

@@ -0,0 +1,104 @@
+# Alias
+
+Mọi nơi một operator được đọc, theo alias, gom theo vùng. Sinh từ `alias/alias.json` (sổ cho máy) và mọi `operator.json` bởi `scripts/generate-alias-doc.mjs`; `--check` chạy trong `npm test`. Operator chỉ đọc những alias mà bảng Context trong `operator.md` của nó gọi tên; trang này là toàn bộ từ vựng mà các bảng đó lấy ra. Phân giải theo tiền tố đăng ký dài nhất, đuôi đường dẫn thu hẹp alias, đoạn trong ngoặc nhọn do lần gọi cung cấp.
+
+## Workspaces — vùng làm việc
+
+Vùng làm việc: các checkout đã route của project đang bind, và khai báo, route, port, danh tính để tìm ra chúng.
+
+| Alias | Tham số | Trỏ tới | Bind | Ai ghi | Operator ràng | Mục đích |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@workspaces` | `<project>`, `<role>` | `<checkout:project/role>  (any routed checkout named explicitly, for cross-project reads: @workspaces/nivo/fe)` | fingerprint + sourceHead (git rev-parse HEAD of the checkout) | — | — | A checkout of another project. The bound project's own are @workspaces/fe and @workspaces/be. |
+| `@workspaces/be` | — | `<checkout:input.project.id/be>  (diskPath from <Source>/.workspaces/local/routes/<project>/be/config.json); friendly segments: /husky, /package, /gates (see segments)` | fingerprint + sourceHead (git rev-parse HEAD of the checkout) | `backend.source.apply` | — | The routed backend checkout of the bound project. |
+| `@workspaces/device-state` | — | `<Source>/.workspaces/device-state.json  (sealed keys live in <Source>/.workspaces/local/credentials/*.key.enc and are bound by name, never read)` | fingerprint | — | — | Machine identity and the encrypted credential roster reference. |
+| `@workspaces/fe` | — | `<checkout:input.project.id/fe>  (diskPath from <Source>/.workspaces/local/routes/<project>/fe/config.json); friendly segments: /husky, /package, /gates, /grammar (see segments)` | fingerprint + sourceHead (git rev-parse HEAD of the checkout) | `frontend.source.apply` | — | The routed frontend checkout of the bound project. |
+| `@workspaces/local/routes` | — | `<Source>/.workspaces/local/routes/<project>/<role>/config.json` | fingerprint | `workspace.bind` | — | Machine-local hydrated routes; project the declarations onto this disk. Ignored by Git. |
+| `@workspaces/ports` | — | `<Source>/.workspaces/ports/<project>.json` | fingerprint | — | — | Port projection: project offset and application slots. Endpoints are derived, never typed. |
+| `@workspaces/projects` | — | `<Source>/.workspaces/projects/<project>/<role>.json` | fingerprint | — | — | Portable route declarations, tracked. The only place a route is declared. |
+
+## Grammar — gói
+
+Gói @starci/grammar như app đang resolve: sự thật duy nhất về việc component sở hữu gì.
+
+| Alias | Tham số | Trỏ tới | Bind | Ai ghi | Operator ràng | Mục đích |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@grammar` | `<family>` | `the @starci/grammar package as the bound app resolves it (file:packages/grammar inside @workspaces/fe today, source 0.4.2; @remote/npm publishes 0.3.0), narrowed to one family <family>: @grammar/core, @grammar/heritage, @grammar/offset-pop; @grammar/common is the shared layer every family imports` | package.json version + the resolved location's fingerprint (checkout head for file:, tarball integrity for npm) | — | — | The Grammar as it runs: Common renderers, props, owned relationships, data-contract claims, and the family's own CSS. The only fact about what a component owns. |
+
+## Knowledge — luật
+
+Luật chuẩn trong cây này: luật UI phổ quát (ui), khẩu vị của họ (grammars), quy ước code (patterns). Chỉ đọc; chủ mới sửa.
+
+| Alias | Tham số | Trỏ tới | Bind | Ai ghi | Operator ràng | Mục đích |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@knowledge/grammars` | — | `<Source>/.claude/knowledge/grammars/<family>/  (DNA.md generated from the package; idioms.md and playbook.md are the owner's taste; family.md holds the visual DNA and the gap table)` | fingerprint per file; DNA.md additionally binds the package version and checkout head it was generated from | — | — | How the family composes: the owner's taste (idioms, playbook) and what exists (DNA). Never the Grammar itself; where a taste row disagrees with @grammar, @grammar is the fact and the row is the finding. |
+| `@knowledge/patterns` | — | `<Source>/.claude/knowledge/patterns/  (fe/, be/)` | fingerprint per file; rule inventory = every `## PREFIX-n` heading in the folder | — | — | Code conventions counted from the two live sources; a rule cites two real paths. |
+| `@knowledge/ui` | — | `<Source>/.claude/knowledge/ui/  (composition/, presentation/, proof/; a sub-path narrows: @knowledge/ui/presentation)` | fingerprint per file; rule inventory = every `## PREFIX-n` heading in the folder | — | — | Universal UI law: what a tree must contain, which value an app boundary takes, what is only true once rendered. |
+
+## Worktrees — thẩm quyền và bằng chứng máy-cục-bộ
+
+Thẩm quyền và bằng chứng máy-cục-bộ ngoài mọi checkout: head nghiệp vụ, UAT pair, nợ, khuôn, runtime owner dùng chung.
+
+| Alias | Tham số | Trỏ tới | Bind | Ai ghi | Operator ràng | Mục đích |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@worktrees/_templates` | — | `<Source>/.worktrees/_templates/  (businesses/, debts/, sessions/, uat/)` | fingerprint per file | — | — | Authority templates for new heads, debts, sessions, and UAT pairs. Consumed, never modified. |
+| `@worktrees/businesses` | — | `<Source>/.worktrees/businesses/  (features/<featureId>/model.json; business-registry-v1.json is the head index; objects/sha256/ the content store)` | content address from business-registry-v1.json featureHeads.&lt;featureId&gt;.head, with authorityStatus | `business.decide` | — | Business promise heads. Its own git worktree; a head binds by content address even before its commit lands. |
+| `@worktrees/debts` | — | `<Source>/.worktrees/debts/  (be.md, fe.md, per-item files)` | fingerprint per file | — | — | Owner-approved quality debts. A debt without a live approval here is not a debt. |
+| `@worktrees/sessions` | — | `<Source>/.worktrees/sessions/<sessionId>/  (state.json; step-<N>/parallel-<M>/ branches, each with request/ and response/ — see @dynamic; central-runtime/ is the shared runtime owner registry outside any session)` | fingerprint per file read | `*` | — | The session container. Operators do not read it directly; they read @dynamic. |
+| `@worktrees/sessions/central-runtime` | — | `<Source>/.worktrees/sessions/central-runtime/owner.json  (generation-<n>-ready.json and logs/ beside it)` | fingerprint + generation | `platform.operate` | — | The shared runtime owner: generation, status, endpoints, health evidence. Callers consume, never own. |
+| `@worktrees/uat` | — | `<Source>/.worktrees/uat/<flow>/  (flow.md: cases in order and named assertions; account.json: username, role, credential name of the single shared UAT password sealed at .stacks/<env>/secrets/uat.enc; seed/records.json and seed/expected.json; runs/<runId>/ append-only: result.json, verdicts.json, captures/<case>.png, sheet.png; latest -> the newest run). <case> narrows to one case of the flow` | fingerprint of snapshot.json and result.json | `uat.verify` | — | UAT authority per flow: the frozen flow, its dedicated account, its seed, and the append-only history of every run with the commit it verified. |
+
+## Remote — internet
+
+Internet. Registry, git remote, kho image, run CI, object storage. Đọc qua mạng; bind bằng version, digest hay head quan sát được.
+
+| Alias | Tham số | Trỏ tới | Bind | Ai ghi | Operator ràng | Mục đích |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@remote/ghcr` | `<image>` | `ghcr.io/<image>@<digest>` | digest | `release.deploy` | — | Immutable release images. A tag is never a binding; a digest is. |
+| `@remote/git` | `<project>`, `<role>` | `the origin URL in @workspaces/local/routes/<project>/<role> (repository.gitRepository)` | observed remote head (git ls-remote) at invocation time | `git.publish` | — | The publication target; fast-forwardness is decided against this observation. |
+| `@remote/github-actions` | `<runId>` | `GitHub Actions run <runId> of the routed repository` | run id + conclusion | — | — | CI evidence of a build or rollout, read only. |
+| `@remote/minio` | `<contentId>`, `<locale>` | `MinIO object contents/<contentId>/<locale>.json through the routed runtime` | fingerprint of the fetched object | `content.generate` | — | Authored lesson content as served, not as drafted. |
+| `@remote/npm` | `<package>` | `the npm registry entry for <package>, e.g. @remote/npm/@starci/grammar@0.3.0` | version + tarball integrity | — | — | Published packages. A version is the binding; latest never is. |
+
+## Dynamic — sinh trong phiên
+
+Sinh trong phiên hiện tại bởi một bước trước và xoá cùng phiên. Không tồn tại trước lần chạy.
+
+| Alias | Tham số | Trỏ tới | Bind | Ai ghi | Operator ràng | Mục đích |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@dynamic` | `<kind>` | `<Source>/.worktrees/sessions/<sessionId>/step-<N>/parallel-<M>/ — one branch of one step. request/request.json is the gate in (orchestrator writes it); response/ is the agent's: response.json (gate out), response.md and other markdown kinds, data/<name>.json, artifacts/<file>; a nested exchange adds <exchange>/request/ and <exchange>/response/. A kind is passed by explicit path in request.json inputs, from the session root. Dynamic files are passed as kinds (templates/kinds/<kind>), never as aliases. The session folder is created by the orchestrator and deleted when git.publish finishes; a blocked run keeps it for resume` | kind contract or schema under templates/kinds; response.json fields is the registry of what a branch produced | `*` | — | Everything produced inside the session and nothing that existed before it. Always dynamic; typed by kind. |
+
+## undefined
+
+
+
+| Alias | Tham số | Trỏ tới | Bind | Ai ghi | Operator ràng | Mục đích |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@tools/browsercontrol` | — | `resources/tools.json#tools.browsercontrol` | mode declared in operator.json → resources.tools; modes: never \| required | — | — | Drive a real browser against a served route: navigate, act, capture screenshots and DOM measurements. |
+| `@tools/ci` | — | `resources/tools.json#tools.ci` | mode declared in operator.json → resources.tools; modes: never \| read \| dispatch | — | — | Observe or dispatch continuous-integration runs. |
+| `@tools/container` | — | `resources/tools.json#tools.container` | mode declared in operator.json → resources.tools; modes: never \| read \| operate | — | — | Inspect or operate containers and images: compose services, GHCR images by digest. |
+| `@tools/database` | — | `resources/tools.json#tools.database` | mode declared in operator.json → resources.tools; modes: never \| read \| namespaced-write | — | — | Read or write the product database for verification: seeds, fixtures, is_uat records. |
+| `@tools/fileread` | — | `resources/tools.json#tools.fileread` | mode declared in operator.json → resources.tools; modes: never \| context-aliases | — | — | Read files and directories at the aliases the Context table names, at the frozen head. |
+| `@tools/git` | — | `resources/tools.json#tools.git` | mode declared in operator.json → resources.tools; modes: never \| read \| commit-session-branch \| merge-and-push | — | — | Read and change repository state: heads, branches, worktrees, commits, merges, pushes. |
+| `@tools/http` | — | `resources/tools.json#tools.http` | mode declared in operator.json → resources.tools; modes: never \| probe | — | — | Probe an endpoint: readiness, health, a served route, a GraphQL typename, a status page. |
+| `@tools/imagegen` | — | `resources/tools.json#tools.imagegen` | mode declared in operator.json → resources.tools; modes: never \| judged \| required | — | — | Produce artwork: a digital image from an image model, made to one stated claim. Rendering HTML is the visualize tool, not this one. |
+| `@tools/objectstorage` | — | `resources/tools.json#tools.objectstorage` | mode declared in operator.json → resources.tools; modes: never \| read \| write | — | — | Read or write objects in the content store (MinIO): curriculum, style references, published units. |
+| `@tools/registry` | — | `resources/tools.json#tools.registry` | mode declared in operator.json → resources.tools; modes: never \| read | — | — | Read a package registry: the published Grammar, its version, its files. |
+| `@tools/secrets` | — | `resources/tools.json#tools.secrets` | mode declared in operator.json → resources.tools; modes: never \| resolve-by-name | — | — | Resolve a sealed credential by name at the moment it is used; never read, print or store its value. |
+| `@tools/shell` | — | `resources/tools.json#tools.shell` | mode declared in operator.json → resources.tools; modes: never \| declared-commands | — | — | Run declared commands: gates, builds, proofs, hooks, deployment plans. |
+| `@tools/sourcewrite` | — | `resources/tools.json#tools.sourcewrite` | mode declared in operator.json → resources.tools; modes: never \| declared-write-set | — | — | Write files inside a routed checkout or an authority root. |
+| `@tools/visualize` | — | `resources/tools.json#tools.visualize` | mode declared in operator.json → resources.tools; modes: never \| html | — | — | Render HTML for a person to look at: direction candidates, audit sheets, alternative comparisons, previews. No model grant is involved. |
+| `@tools/websearch` | — | `resources/tools.json#tools.websearch` | mode declared in operator.json → resources.tools; modes: never \| bounded | — | — | Read public web pages to close one named gap in the evidence; results are references with URLs, never authority. |
+
+## Đoạn thân thiện trong một checkout
+
+Human-friendly segments inside any checkout alias (@workspaces/fe, @workspaces/be, @workspaces/<project>/<role>), mapped to the exact path. Write the friendly word; the resolver substitutes the path.
+
+| Đoạn | Trỏ tới |
+| --- | --- |
+| `husky` | `.husky/  (pre-commit, pre-push)` |
+| `package` | `package.json  (scripts, dependencies, the package version)` |
+| `gates` | `package.json#scripts plus the configs it names (eslint.config.*, tsconfig*.json, jest.config.*/vitest.config.*, sonar-project.properties)` |
+| `grammar` | `packages/grammar  (the @starci/grammar source inside @workspaces/fe)` |
+| `/branch/session` | `the session branch session/<sessionId> of that checkout, in its own git worktree prepared from the frozen head; the only branch a source-writing operator may commit to` |
+| `/commit/<sha>` | `that checkout at one commit; how a later step names exactly what an earlier step wrote (response.json.commits[])` |
+

package/alias/alias.json

@@ -0,0 +1,297 @@
+{
+  "schemaVersion": 8,
+  "note": "Closed registry of reference aliases. An alias reads like the place it names. Static: @workspaces/fe and @workspaces/be (the bound project's routed checkouts), @workspaces/<project>/<role>, @workspaces/{projects,local/routes,ports,device-state}, @grammar/<family>, @knowledge/{ui,grammars,patterns}, @worktrees/{businesses,uat,debts,_templates,sessions/central-runtime}, @remote/{npm,git,ghcr,github-actions,minio}. Dynamic: @dynamic, the current session branch, typed by kind. `<Source>` is the host repository that owns this .claude. A sub-path after a registered alias narrows it; a segment in angle brackets is supplied by the invocation. The registry is a tree: one root per zone, children by path segment, a node with resolvesTo is a definition. Resolution picks the longest registered prefix.",
+  "zones": {
+    "remote": {
+      "en": "Internet. Registries, git remotes, image registries, CI runs, object storage. Read through a network; bound by version, digest, or observed head.",
+      "vi": "Internet. Registry, git remote, kho image, run CI, object storage. Đọc qua mạng; bind bằng version, digest hay head quan sát được."
+    },
+    "grammar": {
+      "en": "The @starci/grammar package as the bound app resolves it: the only fact about what a component owns.",
+      "vi": "Gói @starci/grammar như app đang resolve: sự thật duy nhất về việc component sở hữu gì."
+    },
+    "knowledge": {
+      "en": "Canonical law in this tree: universal UI law (ui), the family's taste (grammars), code conventions (patterns). Read only; edited by the owner.",
+      "vi": "Luật chuẩn trong cây này: luật UI phổ quát (ui), khẩu vị của họ (grammars), quy ước code (patterns). Chỉ đọc; chủ mới sửa."
+    },
+    "workspaces": {
+      "en": "The working area: routed checkouts of the bound project and the declarations, routes, ports, and identity that locate them.",
+      "vi": "Vùng làm việc: các checkout đã route của project đang bind, và khai báo, route, port, danh tính để tìm ra chúng."
+    },
+    "worktrees": {
+      "en": "Machine-local authority and evidence outside any checkout: business heads, UAT pairs, debts, templates, the shared runtime owner.",
+      "vi": "Thẩm quyền và bằng chứng máy-cục-bộ ngoài mọi checkout: head nghiệp vụ, UAT pair, nợ, khuôn, runtime owner dùng chung."
+    },
+    "dynamic": {
+      "en": "Produced inside the current session by an earlier step and deleted with the session. Never exists before the run.",
+      "vi": "Sinh trong phiên hiện tại bởi một bước trước và xoá cùng phiên. Không tồn tại trước lần chạy."
+    }
+  },
+  "segments": {
+    "note": "Human-friendly segments inside any checkout alias (@workspaces/fe, @workspaces/be, @workspaces/<project>/<role>), mapped to the exact path. Write the friendly word; the resolver substitutes the path.",
+    "husky": ".husky/  (pre-commit, pre-push)",
+    "package": "package.json  (scripts, dependencies, the package version)",
+    "gates": "package.json#scripts plus the configs it names (eslint.config.*, tsconfig*.json, jest.config.*/vitest.config.*, sonar-project.properties)",
+    "grammar": "packages/grammar  (the @starci/grammar source inside @workspaces/fe)",
+    "/branch/session": "the session branch session/<sessionId> of that checkout, in its own git worktree prepared from the frozen head; the only branch a source-writing operator may commit to",
+    "/commit/<sha>": "that checkout at one commit; how a later step names exactly what an earlier step wrote (response.json.commits[])"
+  },
+  "tree": {
+    "@workspaces": {
+      "params": [
+        "project",
+        "role"
+      ],
+      "kind": "checkout",
+      "resolvesTo": "<checkout:project/role>  (any routed checkout named explicitly, for cross-project reads: @workspaces/nivo/fe)",
+      "scheme": "source://<repository>",
+      "bind": "fingerprint + sourceHead (git rev-parse HEAD of the checkout)",
+      "writers": [],
+      "purpose": "A checkout of another project. The bound project's own are @workspaces/fe and @workspaces/be.",
+      "fe": {
+        "params": [],
+        "kind": "checkout",
+        "resolvesTo": "<checkout:input.project.id/fe>  (diskPath from <Source>/.workspaces/local/routes/<project>/fe/config.json); friendly segments: /husky, /package, /gates, /grammar (see segments)",
+        "scheme": "source://<repository>",
+        "bind": "fingerprint + sourceHead (git rev-parse HEAD of the checkout)",
+        "writers": [
+          "frontend.source.apply"
+        ],
+        "purpose": "The routed frontend checkout of the bound project."
+      },
+      "be": {
+        "params": [],
+        "kind": "checkout",
+        "resolvesTo": "<checkout:input.project.id/be>  (diskPath from <Source>/.workspaces/local/routes/<project>/be/config.json); friendly segments: /husky, /package, /gates (see segments)",
+        "scheme": "source://<repository>",
+        "bind": "fingerprint + sourceHead (git rev-parse HEAD of the checkout)",
+        "writers": [
+          "backend.source.apply"
+        ],
+        "purpose": "The routed backend checkout of the bound project."
+      },
+      "projects": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.workspaces/projects/<project>/<role>.json",
+        "scheme": "workspace://declarations/<project>",
+        "bind": "fingerprint",
+        "writers": [],
+        "purpose": "Portable route declarations, tracked. The only place a route is declared."
+      },
+      "local": {
+        "routes": {
+          "params": [],
+          "kind": "dir",
+          "resolvesTo": "<Source>/.workspaces/local/routes/<project>/<role>/config.json",
+          "scheme": "workspace://routes/<project>/<role>",
+          "bind": "fingerprint",
+          "writers": [
+            "workspace.bind"
+          ],
+          "purpose": "Machine-local hydrated routes; project the declarations onto this disk. Ignored by Git."
+        }
+      },
+      "ports": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.workspaces/ports/<project>.json",
+        "scheme": "workspace://ports/<project>",
+        "bind": "fingerprint",
+        "writers": [],
+        "purpose": "Port projection: project offset and application slots. Endpoints are derived, never typed."
+      },
+      "device-state": {
+        "params": [],
+        "kind": "file",
+        "resolvesTo": "<Source>/.workspaces/device-state.json  (sealed keys live in <Source>/.workspaces/local/credentials/*.key.enc and are bound by name, never read)",
+        "scheme": "workspace://identity/device",
+        "bind": "fingerprint",
+        "writers": [],
+        "purpose": "Machine identity and the encrypted credential roster reference."
+      }
+    },
+    "@knowledge": {
+      "ui": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.claude/knowledge/ui/  (composition/, presentation/, proof/; a sub-path narrows: @knowledge/ui/presentation)",
+        "scheme": "knowledge://ui/<group>/<topic>",
+        "bind": "fingerprint per file; rule inventory = every `## PREFIX-n` heading in the folder",
+        "writers": [],
+        "purpose": "Universal UI law: what a tree must contain, which value an app boundary takes, what is only true once rendered."
+      },
+      "grammars": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.claude/knowledge/grammars/<family>/  (DNA.md generated from the package; idioms.md and playbook.md are the owner's taste; family.md holds the visual DNA and the gap table)",
+        "scheme": "knowledge://grammars/<family>/<topic>",
+        "bind": "fingerprint per file; DNA.md additionally binds the package version and checkout head it was generated from",
+        "writers": [],
+        "purpose": "How the family composes: the owner's taste (idioms, playbook) and what exists (DNA). Never the Grammar itself; where a taste row disagrees with @grammar, @grammar is the fact and the row is the finding."
+      },
+      "patterns": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.claude/knowledge/patterns/  (fe/, be/)",
+        "scheme": "knowledge://patterns/<side>/<topic>",
+        "bind": "fingerprint per file; rule inventory = every `## PREFIX-n` heading in the folder",
+        "writers": [],
+        "purpose": "Code conventions counted from the two live sources; a rule cites two real paths."
+      }
+    },
+    "@worktrees": {
+      "businesses": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.worktrees/businesses/  (features/<featureId>/model.json; business-registry-v1.json is the head index; objects/sha256/ the content store)",
+        "scheme": "business://<featureId>",
+        "bind": "content address from business-registry-v1.json featureHeads.<featureId>.head, with authorityStatus",
+        "writers": [
+          "business.decide"
+        ],
+        "purpose": "Business promise heads. Its own git worktree; a head binds by content address even before its commit lands."
+      },
+      "sessions": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.worktrees/sessions/<sessionId>/  (state.json; step-<N>/parallel-<M>/ branches, each with request/ and response/ — see @dynamic; central-runtime/ is the shared runtime owner registry outside any session)",
+        "scheme": "session://<sessionId>",
+        "bind": "fingerprint per file read",
+        "writers": [
+          "*"
+        ],
+        "purpose": "The session container. Operators do not read it directly; they read @dynamic.",
+        "central-runtime": {
+          "params": [],
+          "kind": "file",
+          "resolvesTo": "<Source>/.worktrees/sessions/central-runtime/owner.json  (generation-<n>-ready.json and logs/ beside it)",
+          "scheme": "runtime://owner",
+          "bind": "fingerprint + generation",
+          "writers": [
+            "platform.operate"
+          ],
+          "purpose": "The shared runtime owner: generation, status, endpoints, health evidence. Callers consume, never own."
+        }
+      },
+      "uat": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.worktrees/uat/<flow>/  (flow.md: cases in order and named assertions; account.json: username, role, credential name of the single shared UAT password sealed at .stacks/<env>/secrets/uat.enc; seed/records.json and seed/expected.json; runs/<runId>/ append-only: result.json, verdicts.json, captures/<case>.png, sheet.png; latest -> the newest run). <case> narrows to one case of the flow",
+        "scheme": "uat://<flow>/<case>",
+        "bind": "fingerprint of snapshot.json and result.json",
+        "writers": [
+          "uat.verify"
+        ],
+        "purpose": "UAT authority per flow: the frozen flow, its dedicated account, its seed, and the append-only history of every run with the commit it verified."
+      },
+      "debts": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.worktrees/debts/  (be.md, fe.md, per-item files)",
+        "scheme": "debt://<file>",
+        "bind": "fingerprint per file",
+        "writers": [],
+        "purpose": "Owner-approved quality debts. A debt without a live approval here is not a debt."
+      },
+      "_templates": {
+        "params": [],
+        "kind": "dir",
+        "resolvesTo": "<Source>/.worktrees/_templates/  (businesses/, debts/, sessions/, uat/)",
+        "scheme": "template://<kind>",
+        "bind": "fingerprint per file",
+        "writers": [],
+        "purpose": "Authority templates for new heads, debts, sessions, and UAT pairs. Consumed, never modified."
+      }
+    },
+    "@grammar": {
+      "params": [
+        "family"
+      ],
+      "kind": "checkout",
+      "resolvesTo": "the @starci/grammar package as the bound app resolves it (`file:packages/grammar` inside @workspaces/fe today, source 0.4.2; @remote/npm publishes 0.3.0), narrowed to one family <family>: @grammar/core, @grammar/heritage, @grammar/offset-pop; @grammar/common is the shared layer every family imports",
+      "scheme": "grammar://<family>@<version>",
+      "bind": "package.json version + the resolved location's fingerprint (checkout head for file:, tarball integrity for npm)",
+      "writers": [],
+      "purpose": "The Grammar as it runs: Common renderers, props, owned relationships, data-contract claims, and the family's own CSS. The only fact about what a component owns."
+    },
+    "@remote": {
+      "npm": {
+        "params": [
+          "package"
+        ],
+        "kind": "service",
+        "resolvesTo": "the npm registry entry for <package>, e.g. @remote/npm/@starci/grammar@0.3.0",
+        "scheme": "npm://<package>@<version>",
+        "bind": "version + tarball integrity",
+        "writers": [],
+        "purpose": "Published packages. A version is the binding; latest never is."
+      },
+      "git": {
+        "params": [
+          "project",
+          "role"
+        ],
+        "kind": "service",
+        "resolvesTo": "the origin URL in @workspaces/local/routes/<project>/<role> (repository.gitRepository)",
+        "scheme": "remote://<repository>/<branch>",
+        "bind": "observed remote head (git ls-remote) at invocation time",
+        "writers": [
+          "git.publish"
+        ],
+        "purpose": "The publication target; fast-forwardness is decided against this observation."
+      },
+      "ghcr": {
+        "params": [
+          "image"
+        ],
+        "kind": "service",
+        "resolvesTo": "ghcr.io/<image>@<digest>",
+        "scheme": "oci://ghcr.io/<image>",
+        "bind": "digest",
+        "writers": [
+          "release.deploy"
+        ],
+        "purpose": "Immutable release images. A tag is never a binding; a digest is."
+      },
+      "github-actions": {
+        "params": [
+          "runId"
+        ],
+        "kind": "service",
+        "resolvesTo": "GitHub Actions run <runId> of the routed repository",
+        "scheme": "workflow-run://github-actions/<runId>",
+        "bind": "run id + conclusion",
+        "writers": [],
+        "purpose": "CI evidence of a build or rollout, read only."
+      },
+      "minio": {
+        "params": [
+          "contentId",
+          "locale"
+        ],
+        "kind": "service",
+        "resolvesTo": "MinIO object contents/<contentId>/<locale>.json through the routed runtime",
+        "scheme": "content://<contentId>/<locale>",
+        "bind": "fingerprint of the fetched object",
+        "writers": [
+          "content.generate"
+        ],
+        "purpose": "Authored lesson content as served, not as drafted."
+      }
+    },
+    "@dynamic": {
+      "params": [
+        "kind"
+      ],
+      "kind": "dir",
+      "resolvesTo": "<Source>/.worktrees/sessions/<sessionId>/step-<N>/parallel-<M>/ — one branch of one step. request/request.json is the gate in (orchestrator writes it); response/ is the agent's: response.json (gate out), response.md and other markdown kinds, data/<name>.json, artifacts/<file>; a nested exchange adds <exchange>/request/ and <exchange>/response/. A kind is passed by explicit path in request.json inputs, from the session root. Dynamic files are passed as kinds (templates/kinds/<kind>), never as aliases. The session folder is created by the orchestrator and deleted when git.publish finishes; a blocked run keeps it for resume",
+      "scheme": "step://<sessionId>/<N>/<M>/<path>",
+      "bind": "kind contract or schema under templates/kinds; response.json fields is the registry of what a branch produced",
+      "writers": [
+        "*"
+      ],
+      "purpose": "Everything produced inside the session and nothing that existed before it. Always dynamic; typed by kind."
+    }
+  }
+}

package/bin/starci-skills.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// The installer for StarCi Skills. The runtime is a tree of files under <repo>/.claude and two
+// bootstrap files at the repo root (CLAUDE.md for Claude Code, AGENTS.md for Codex); nothing here is
+// a framework the tree depends on at run time. The CLI has no dependencies and needs Node 20+.
+//
+//   npx @starci/skills init            install the tree into ./.claude and write the bootstraps
+//   npx @starci/skills update          bring an installed tree to this package's version
+//   npx @starci/skills doctor          run the tree's own validators on the installed copy
+//   npx @starci/skills version
+//
+// Every command takes --dir <repo> (default: the current directory). init refuses a non-empty
+// .claude it did not install unless --force; update keeps a file a person changed locally unless
+// --force; neither ever runs a git command.
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+
+// What an installed tree is made of. Only these paths are copied, hashed and updated; anything else
+// a person adds beside them (a tests/ folder, notes) is theirs and is never touched.
+export const PAYLOAD = [
+  'INDEX.md', 'INDEX.vi.md', 'SKILL.md', 'SKILL.vi.md', 'routing.json',
+  'alias', 'knowledge', 'operators', 'readiness', 'resources', 'scripts', 'templates', 'workflows',
+];
+const MANIFEST = '.starci-skills.json';
+const SESSIONS_IGNORE = '.worktrees/sessions/';
+
+const BOOTSTRAP = `# StarCi agent bootstrap
+
+Before planning, reading target source, or running a skill, read
+[\`<Source>/.claude/INDEX.md\`](.claude/INDEX.md) completely and follow its load order.
+
+\`<Source>\` is the single host repository that owns this bootstrap and the \`.claude\` runtime. A routed
+repository checkout or Git worktree follows that Source; do not rebind \`<Source>\` to it or expect it to
+contain another \`.claude/INDEX.md\`.
+
+This file is only a bootstrap. Do not copy context, brainstorm, compiler, gate or skill rules into it:
+the entry routes, and a rule copied here becomes a second home that nobody remembers to update.
+`;
+
+// The validators the tree ships, in the order npm test runs them. --quick keeps the three that
+// finish in seconds; the full doctor also runs the operator self-tests and the script specs.
+const DOCTOR_QUICK = ['validate-routing.mjs', 'validate-alias.mjs', 'validate-operator.mjs'];
+const DOCTOR_FULL = [
+  'validate-routing.mjs', 'validate-resources.mjs', 'validate-knowledge-citations.mjs', 'validate-alias.mjs',
+  ['generate-alias-doc.mjs', '--check'], 'validate-operator.mjs', 'validate-workflows.mjs', 'validate-defaults.mjs',
+  ['generate-operators-index.mjs', '--check'], 'validate-templates.mjs', 'run-operator-self-tests.mjs',
+];
+
+function parseArgs(argv) {
+  const out = { command: argv[0] ?? 'help', dir: process.cwd(), force: false, quick: false, bootstrap: true };
+  for (let i = 1; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--dir') out.dir = path.resolve(argv[++i] ?? '.');
+    else if (a.startsWith('--dir=')) out.dir = path.resolve(a.slice(6));
+    else if (a === '--force') out.force = true;
+    else if (a === '--quick') out.quick = true;
+    else if (a === '--no-bootstrap') out.bootstrap = false;
+    else if (a === '-h' || a === '--help') out.command = 'help';
+    else throw new Error(`unknown argument ${a}`);
+  }
+  return out;
+}
+
+function walk(root, rel = '') {
+  const abs = path.join(root, rel);
+  if (!existsSync(abs)) return [];
+  if (statSync(abs).isFile()) return [rel];
+  const out = [];
+  for (const e of readdirSync(abs, { withFileTypes: true })) {
+    const next = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) out.push(...walk(root, next));
+    else out.push(next);
+  }
+  return out;
+}
+const sha = (file) => createHash('sha256').update(readFileSync(file).toString('utf8').replace(/\r\n/g, '\n')).digest('hex');
+const payloadFiles = (root) => PAYLOAD.flatMap((p) => walk(root, p)).sort();
+const hashTree = (root) => Object.fromEntries(payloadFiles(root).map((rel) => [rel, sha(path.join(root, rel))]));
+
+function readManifest(target) {
+  const file = path.join(target, MANIFEST);
+  return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null;
+}
+function writeManifest(target, kept = []) {
+  const manifest = { name: pkg.name, version: pkg.version, installedAt: new Date().toISOString(), files: hashTree(target) };
+  if (kept.length) manifest.keptLocal = kept;
+  writeFileSync(path.join(target, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+function copyPayload(target) {
+  for (const p of PAYLOAD) {
+    const from = path.join(packageRoot, p);
+    const to = path.join(target, p);
+    if (!existsSync(from)) throw new Error(`package is incomplete: ${p} is missing`);
+    if (statSync(from).isDirectory()) { rmSync(to, { recursive: true, force: true }); cpSync(from, to, { recursive: true }); }
+    else { mkdirSync(path.dirname(to), { recursive: true }); cpSync(from, to); }
+  }
+}
+
+function writeBootstraps(repo, log) {
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    const file = path.join(repo, name);
+    if (!existsSync(file)) { writeFileSync(file, BOOTSTRAP); log(`wrote ${name}`); continue; }
+    const current = readFileSync(file, 'utf8');
+    if (current.includes('.claude/INDEX.md')) log(`kept ${name} (already routes to .claude/INDEX.md)`);
+    else log(`NOTICE ${name} exists and does not route to .claude/INDEX.md; add the bootstrap paragraph yourself`);
+  }
+  const ignore = path.join(repo, '.gitignore');
+  const lines = existsSync(ignore) ? readFileSync(ignore, 'utf8').split(/\r?\n/) : [];
+  if (!lines.some((l) => l.trim() === SESSIONS_IGNORE || l.trim() === '.worktrees/' || l.trim() === '.worktrees')) {
+    appendFileSync(ignore, `${lines.length && lines.at(-1) !== '' ? '\n' : ''}# StarCi Skills sessions live here and are never committed\n${SESSIONS_IGNORE}\n`);
+    log(`added ${SESSIONS_IGNORE} to .gitignore`);
+  }
+}
+
+export function init(opts, log = console.log) {
+  const repo = opts.dir;
+  const target = path.join(repo, '.claude');
+  if (!existsSync(repo)) throw new Error(`${repo} does not exist`);
+  const manifest = readManifest(target);
+  if (existsSync(target) && readdirSync(target).length && !manifest && !opts.force) {
+    throw new Error(`${target} exists and was not installed by ${pkg.name}; move it away or pass --force to replace the runtime paths inside it`);
+  }
+  if (manifest) log(`re-installing over ${manifest.name}@${manifest.version} (use "update" to keep local changes)`);
+  mkdirSync(target, { recursive: true });
+  copyPayload(target);
+  const written = writeManifest(target);
+  log(`installed ${pkg.name}@${pkg.version} into ${target} (${Object.keys(written.files).length} files)`);
+  if (opts.bootstrap) writeBootstraps(repo, log);
+  log('next: open the repo with Claude Code or Codex; the bootstrap routes every agent to .claude/INDEX.md');
+  return written;
+}
+
+export function update(opts, log = console.log) {
+  const target = path.join(opts.dir, '.claude');
+  const manifest = readManifest(target);
+  if (!manifest) throw new Error(`${target} has no ${MANIFEST}; run init first`);
+  const before = hashTree(target);
+  const locallyChanged = Object.entries(before).filter(([rel, h]) => manifest.files[rel] && manifest.files[rel] !== h).map(([rel]) => rel);
+  const locallyAdded = Object.keys(before).filter((rel) => !manifest.files[rel]);
+  const saved = Object.fromEntries([...locallyChanged, ...locallyAdded].map((rel) => [rel, readFileSync(path.join(target, rel))]));
+  copyPayload(target);
+  const kept = [];
+  if (!opts.force) {
+    for (const [rel, bytes] of Object.entries(saved)) {
+      const file = path.join(target, rel);
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, bytes);
+      kept.push(rel);
+    }
+  }
+  const written = writeManifest(target, kept);
+  log(`updated ${manifest.name}@${manifest.version} -> ${pkg.name}@${pkg.version} in ${target}`);
+  for (const rel of kept) log(`kept ${rel} (changed locally; pass --force to take the package version)`);
+  if (opts.force && (locallyChanged.length || locallyAdded.length)) log(`replaced ${locallyChanged.length + locallyAdded.length} locally changed file(s)`);
+  return written;
+}
+
+export function doctor(opts, log = console.log) {
+  const target = path.join(opts.dir, '.claude');
+  if (!existsSync(path.join(target, 'scripts'))) throw new Error(`${target} has no scripts/; run init first`);
+  const manifest = readManifest(target);
+  if (manifest) {
+    const drift = Object.entries(hashTree(target)).filter(([rel, h]) => manifest.files[rel] && manifest.files[rel] !== h).map(([rel]) => rel);
+    log(`${manifest.name}@${manifest.version}; ${drift.length} file(s) changed since install${drift.length ? `: ${drift.join(', ')}` : ''}`);
+  } else log(`no ${MANIFEST}: validating an unmanaged tree`);
+  const steps = opts.quick ? DOCTOR_QUICK : DOCTOR_FULL;
+  let failed = 0;
+  for (const step of steps) {
+    const [script, ...args] = Array.isArray(step) ? step : [step];
+    const r = spawnSync(process.execPath, [path.join(target, 'scripts', script), ...args], { cwd: target, encoding: 'utf8' });
+    const ok = r.status === 0;
+    if (!ok) failed += 1;
+    log(`${ok ? 'ok  ' : 'FAIL'} ${script}${args.length ? ` ${args.join(' ')}` : ''}${ok ? '' : `\n${(r.stdout + r.stderr).trim()}`}`);
+  }
+  if (!opts.quick) {
+    const specs = readdirSync(path.join(target, 'scripts')).filter((f) => f.endsWith('.spec.mjs')).map((f) => path.join(target, 'scripts', f));
+    const r = spawnSync(process.execPath, ['--test', ...specs], { cwd: target, encoding: 'utf8' });
+    if (r.status !== 0) failed += 1;
+    log(`${r.status === 0 ? 'ok  ' : 'FAIL'} node --test scripts/*.spec.mjs (${specs.length} files)${r.status === 0 ? '' : `\n${(r.stdout + r.stderr).trim().split('\n').slice(-30).join('\n')}`}`);
+  }
+  log(failed ? `doctor: ${failed} check(s) failed` : 'doctor: the installed tree validates');
+  return failed;
+}
+
+const HELP = `${pkg.name} ${pkg.version}
+
+  npx ${pkg.name} init   [--dir <repo>] [--force] [--no-bootstrap]
+  npx ${pkg.name} update [--dir <repo>] [--force]
+  npx ${pkg.name} doctor [--dir <repo>] [--quick]
+  npx ${pkg.name} version
+
+init    copies the runtime into <repo>/.claude, writes CLAUDE.md and AGENTS.md when absent, and
+        adds .worktrees/sessions/ to .gitignore. Refuses a .claude it did not install unless --force.
+update  replaces the runtime paths with this version; a file changed locally is kept and listed
+        unless --force. Files outside the runtime paths are never touched.
+doctor  runs the tree's own validators on the installed copy and reports local drift.
+`;
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.command === 'init') init(opts);
+    else if (opts.command === 'update') update(opts);
+    else if (opts.command === 'doctor') process.exitCode = doctor(opts) ? 1 : 0;
+    else if (opts.command === 'version') console.log(pkg.version);
+    else console.log(HELP);
+  } catch (err) {
+    console.error(`${pkg.name}: ${err.message}`);
+    process.exitCode = 1;
+  }
+}