@starci/skills 1.1.0

package/INDEX.md

@@ -0,0 +1,74 @@
+# StarCi Skills 1.1.0
+
+This tree is the runtime. Read [SKILL.md](SKILL.md) next; it is the single entry that freezes a
+mission's scope, selects the one operator that owns the outcome, and routes between operators on
+typed results.
+
+## Load order
+
+1. `SKILL.md` — entry, routing loop, and the authority statement.
+2. `routing.json` — the closed map from every domain a stop code hands to (see the Stop codes table of
+   `operators/INDEX.md`) to its next step. It is validated against the operators' Stops tables, so a
+   missing route is a build failure. `workflows/` holds the example chains the entry reuses.
+3. `resources/` — which execution profile runs each operator role, which runtime grants it may use,
+   and its standing answers on web search, Grammar binding, and image generation. Also validated.
+4. The one operator the mission needs: its `operator.md` (Job, Context, Inputs, Requirements, Steps,
+   Outputs, Stops, Next) plus `operator.json` (id, domain, resources). Stop codes resolve through the
+   Stop codes table of `operators/INDEX.md`.
+5. Only the knowledge topics that operator binds.
+
+Do not preload the tree. An operator binds the smallest set of topics its decision needs, each with
+its fingerprint and complete rule inventory, and may emit no identifier outside that inventory.
+
+## Layout
+
+```text
+SKILL.md                 one entry, fourteen operators, one routing map
+routing.json             14 operators, 68 routes, four kinds: operator | resume | user | external
+alias/                   alias.json (machine registry: location, scheme, binding, writers, zone) + INDEX.md (generated map by zone); every operator reads by alias only
+resources/               tools.json (the closed tool registry: modes and per-runtime support, addressed as @tools/<id>) + agents/profiles/{openai,claude}.json (6 profiles, permits per tool) + orchestrator.json (one agent per operator, max 3, profile equivalents); validated
+workflows/               example chains (steps of parallel branches, loops, presets) the entry reuses when a request matches their when; otherwise it composes its own under the same rules; validated
+operators/INDEX.md       generated: what each operator reads, which kinds it consumes and produces, its steps, and every stop code with its disposition; operators/errors.json holds the codes several operators share
+operators/<id>/          operator.md (+vi) one authored file per operator, operator.json (id, domain, resources), errors.json (its own codes), validate.mjs, self-test.mjs
+knowledge/
+  ui/composition/        what a tree must contain, before it exists   -> frontend.direction.decide
+  ui/presentation/       which CSS value an app-owned boundary takes  -> frontend.presentation.resolve
+  ui/proof/              what is only true once rendered              -> frontend.surface.audit
+  patterns/fe, be        code conventions extracted from the two live sources
+  grammars/<family>/     one visual family's realization of Common
+templates/               one template per document kind; each carries the json template-contract the tree is checked against;
+                         kinds/ types every file that crosses between steps (<kind>.contract.json + <kind>.skeleton.md for markdown, <kind>.schema.json for data); step/ holds the request.json and response.json gates
+scripts/                 validate-routing.mjs, validate-resources.mjs, validate-knowledge-citations.mjs, validate-alias.mjs, validate-templates.mjs, validate-operator.mjs, validate-workflows.mjs, validate-request.mjs, validate-response.mjs, validate-step.mjs, run-operator-self-tests.mjs;
+                         device-state.mjs and workspace-portable.mjs (+ specs), which the backend package.json calls
+readiness/               workspaces/ schemas that the portable and hydrated route declarations name as $schema
+```
+
+`npm test` runs the routing validation, the resources validation, the knowledge citation check, the template check, every operator self-test, and the script specs. It is green at the published
+head or the head is not publishable.
+
+## Rules that hold everywhere
+
+- An operator performs one job in one linear pass. It never calls another operator, routes a
+  workflow, pauses internally, or returns free-form control instructions. The parent alone maps a
+  validated output to the next transition.
+- Only a validated field routes. Prose in a receipt, a narrated outcome, or an output that failed its
+  validator does not route.
+- Authority lives in operator schemas, not in this file or in `SKILL.md`. `git.publish` cannot
+  express a force push; `release.deploy` cannot run without its declared authorization;
+  `uat.verify` has no field that can hold a credential.
+- English `.md` files are the only runtime authority. Same-stem `.vi.md` files are human mirrors and
+  never enter a context manifest, dependency list, validator input, or operator binding.
+- Rule IDs are stable public addresses. Append; never renumber, reuse, or silently change meaning.
+
+## Lineage
+
+1.1.0 (2026-09-03): the tree ships as the npm package @starci/skills; npx @starci/skills init installs it as a repository's .claude runtime with the CLAUDE.md and AGENTS.md bootstraps, update keeps local edits, doctor runs the validators on the installed copy; @starci/grammar 0.4.2 (the core entry re-exports Common).
+
+1.0.3 (2026-09-03): a tools registry replaces grants and policies (resources/tools.json, @tools/<id> in Steps, per-runtime support, profile equivalents); every operator binds an OpenAI profile for the Codex processor; the first test round (tests/) and its fixes; docs/ and sites/ return.
+
+1.0.2 (2026-09-03): every operator is one authored operator.md with a request/response branch layout, JSON kind contracts, an errors registry with dispositions, example workflows, and the frontend.*/backend.source.apply names; 1.0.1 was the dry-run round that exposed the old shape.
+
+
+This tree replaced the v7.6 runtime on 2026-09-02. The complete v7.6 tree, including its 13 skills,
+113 operators, templates, and runtime contracts, is preserved on the `v7` branch of this repository.
+A v8 document that cites a v7-only file names that branch.

package/INDEX.vi.md

@@ -0,0 +1,75 @@
+# StarCi Skills 1.1.0
+
+Cây này chính là runtime. Đọc tiếp `SKILL.vi.md` nếu có, hoặc `SKILL.md`; đó là cửa vào duy nhất,
+đóng băng phạm vi của một nhiệm vụ, chọn đúng một operator sở hữu kết quả, rồi định tuyến giữa các
+operator dựa trên kết quả có kiểu.
+
+## Thứ tự nạp
+
+1. `SKILL.md`: cửa vào, vòng lặp định tuyến, và tuyên bố về thẩm quyền.
+2. `routing.json`: bảng đóng ánh xạ mọi domain mà mã dừng bàn giao tới (xem bảng Mã dừng trong
+   `operators/INDEX.md`) sang bước kế tiếp. Bảng được kiểm đối chiếu với bảng Dừng của các operator,
+   nên thiếu một route là lỗi build. `workflows/` giữ các chuỗi mẫu mà cửa vào dùng lại.
+3. `resources/`: profile thực thi nào chạy từng vai trò của operator, nó được dùng quyền nào lúc
+   chạy, và câu trả lời thường trực về tìm mạng, ràng Grammar, sinh hình. Cũng được kiểm.
+4. Đúng một operator mà nhiệm vụ cần: `operator.md` (Việc, Context, Đầu vào, Yêu cầu, Các bước, Đầu ra,
+   Dừng, Kế tiếp) cùng `operator.json` (id, domain, resources). Mã dừng tra ở bảng Mã dừng trong `operators/INDEX.md`.
+5. Chỉ những topic knowledge mà operator đó bind.
+
+Không nạp trước cả cây. Một operator bind tập topic nhỏ nhất mà quyết định của nó cần, mỗi topic kèm
+fingerprint và danh sách rule đầy đủ, và không được phát ra mã nào ngoài danh sách ấy.
+
+## Bố cục
+
+```text
+SKILL.md                 một cửa vào, mười bốn operator, một bảng định tuyến
+routing.json             14 operator, 68 route, bốn loại: operator | resume | user | external
+alias/                   alias.json (sổ cho máy: vị trí, scheme, bind, ai ghi, vùng) + INDEX.md (bản đồ sinh theo vùng); operator chỉ đọc qua alias
+resources/               tools.json (sổ tool đóng: mode và hỗ trợ theo runtime, gọi bằng @tools/<id>) + agents/profiles/{openai,claude}.json (6 profile, quyền theo tool) + orchestrator.json (mỗi operator một agent, tối đa 3, profile tương đương); có kiểm
+workflows/               chuỗi mẫu (các bậc gồm nhánh song song, vòng lặp, preset) mà cửa vào dùng lại khi request khớp when; không khớp thì tự ghép theo cùng luật; có kiểm
+operators/INDEX.md       sinh tự động: mỗi operator đọc gì, tiêu thụ và sinh kind nào, số bước, và mọi mã dừng kèm cách xử lý; operators/errors.json giữ mã dùng chung
+operators/<id>/          operator.md (+vi) một file viết tay cho mỗi operator, operator.json (id, domain, resources), errors.json (mã riêng), validate.mjs, self-test.mjs
+knowledge/
+  ui/composition/        cây phải chứa gì, trước khi nó tồn tại      -> frontend.direction.decide
+  ui/presentation/       ranh giới do app sở hữu lấy giá trị CSS nào -> frontend.presentation.resolve
+  ui/proof/              thứ chỉ đúng sai sau khi đã render          -> frontend.surface.audit
+  patterns/fe, be        quy ước code trích từ hai source thật
+  grammars/<họ>/         cách một họ hình ảnh hiện thực Common
+templates/               mỗi loại tài liệu một template; mỗi template mang khối json template-contract dùng để kiểm cả cây;
+                         kinds/ định kiểu mọi file đi qua giữa các bước (<kind>.contract.json + <kind>.skeleton.md cho markdown, <kind>.schema.json cho dữ liệu); step/ giữ hai gate request.json và response.json
+scripts/                 validate-routing.mjs, validate-resources.mjs, validate-knowledge-citations.mjs, validate-alias.mjs, validate-templates.mjs, validate-operator.mjs, validate-workflows.mjs, validate-request.mjs, validate-response.mjs, validate-step.mjs, run-operator-self-tests.mjs;
+                         device-state.mjs và workspace-portable.mjs (+ spec), thứ package.json của backend gọi tới
+readiness/               các schema workspaces/ mà khai báo route portable và hydrate gọi tên trong $schema
+```
+
+`npm test` chạy kiểm định tuyến, kiểm resources, kiểm trích dẫn knowledge, kiểm template, mọi self-test của operator, và các spec của script. Head đã publish phải xanh, không xanh
+thì không được publish.
+
+## Luật áp dụng khắp nơi
+
+- Một operator làm đúng một việc trong một lượt tuyến tính. Nó không gọi operator khác, không điều
+  phối workflow, không tự dừng giữa chừng, không trả chỉ dẫn điều khiển dạng văn xuôi. Chỉ cha mới
+  ánh xạ một output đã validate sang bước chuyển kế tiếp.
+- Chỉ trường đã validate mới định tuyến được. Văn xuôi trong receipt, kết quả kể bằng lời, hay
+  output trượt validator đều không định tuyến.
+- Thẩm quyền nằm trong schema của operator, không nằm ở file này hay ở `SKILL.md`. `git.publish`
+  không diễn đạt được force push; `release.deploy` không chạy nổi khi thiếu authorization đã khai;
+  `uat.verify` không có trường nào chứa nổi credential.
+- File `.md` tiếng Anh là authority duy nhất lúc chạy. File `.vi.md` cùng tên là bản đọc cho người,
+  không bao giờ vào context manifest, danh sách phụ thuộc, input của validator, hay binding của
+  operator.
+- Mã rule là địa chỉ công khai ổn định. Chỉ thêm; không đánh số lại, không dùng lại, không lặng lẽ
+  đổi nghĩa.
+
+## Dòng dõi
+
+1.1.0 (2026-09-03): cây phát hành thành gói npm @starci/skills; npx @starci/skills init cài nó làm runtime .claude của một repository kèm bootstrap CLAUDE.md và AGENTS.md, update giữ sửa đổi tay, doctor chạy validator trên bản đã cài; @starci/grammar 0.4.2 (entry core re-export Common).
+
+1.0.3 (2026-09-03): sổ tool thay cho grant và policy (resources/tools.json, @tools/<id> trong Các bước, hỗ trợ theo runtime, profile tương đương); mọi operator ràng profile OpenAI cho processor Codex; vòng test đầu (tests/) và các sửa từ đó; docs/ và sites/ trở lại.
+
+1.0.2 (2026-09-03): mọi operator là một operator.md viết tay với layout nhánh request/response, hợp đồng kind JSON, sổ mã dừng có cách xử lý, workflow mẫu, và tên frontend.* / backend.source.apply; 1.0.1 là vòng chạy khô đã lộ ra dạng cũ.
+
+
+Cây này thay thế runtime v7.6 vào ngày 2026-09-02. Toàn bộ cây v7.6, gồm 13 skill, 113 operator,
+template và các contract runtime, được giữ nguyên trên nhánh `v7` của cùng repository. Tài liệu v8
+nào dẫn tới một file chỉ có ở v7 thì gọi tên nhánh đó.

package/README.md

@@ -0,0 +1,44 @@
+# @starci/skills
+
+StarCi Skills is the `.claude` runtime of a repository: one entry (`SKILL.md`), fourteen operators,
+eight example workflows, one closed routing map and one tool registry. An agent in Claude Code or
+Codex reads `.claude/INDEX.md` through a one-paragraph bootstrap and follows its load order; the tree
+does the rest. Documentation: <https://harness.starci.org/docs/>. Tiếng Việt: [README.vi.md](README.vi.md).
+
+## Install
+
+```bash
+npx @starci/skills init
+```
+
+Run it at the root of the repository that will own the runtime. It copies the tree into `./.claude`,
+writes `CLAUDE.md` (read by Claude Code) and `AGENTS.md` (read by Codex) when they do not exist, and
+adds `.worktrees/sessions/` to `.gitignore`, where sessions live. Commit `.claude/` with the repository:
+it is source, not a cache. Requires Node 20 or newer; the CLI has no dependencies.
+
+| Command | What it does |
+| --- | --- |
+| `npx @starci/skills init [--dir <repo>] [--force] [--no-bootstrap]` | Installs the tree and the bootstraps. Refuses a populated `.claude` it did not install unless `--force`, and even then replaces only the runtime paths. |
+| `npx @starci/skills update [--dir <repo>] [--force]` | Brings an installed tree to this package's version. A file changed locally is kept and listed; `--force` takes the package version. Files outside the runtime paths are never touched. |
+| `npx @starci/skills doctor [--dir <repo>] [--quick]` | Runs the tree's own validators on the installed copy (routing, alias, operators, workflows, defaults, templates, knowledge citations, the operator self-tests and the script specs) and reports files changed since install. |
+| `npx @starci/skills version` | Prints the package version. |
+
+The runtime paths are `INDEX.md`, `INDEX.vi.md`, `SKILL.md`, `SKILL.vi.md`, `routing.json`, `alias/`,
+`knowledge/`, `operators/`, `readiness/`, `resources/`, `scripts/`, `templates/`, `workflows/`. The
+manifest `.claude/.starci-skills.json` records the installed version and a hash per file; `update` and
+`doctor` read it.
+
+## Claude Code and Codex
+
+Both runtimes are entered the same way. `CLAUDE.md` and `AGENTS.md` carry the same bootstrap: read
+`.claude/INDEX.md` completely and follow its load order. The processor runs each operator on the profile
+its `operator.json` binds (`resources/agents/profiles/openai.json` for Codex, `claude.json` for Claude
+Code, paired in `resources/orchestrator.json`), and each operator may call only the tools its
+`operator.json` declares from `resources/tools.json`. The English files are the runtime authority; the
+`.vi.md` siblings are for people.
+
+## Develop
+
+This repository is the package. `npm test` runs every validator, the operator self-tests, the script
+specs and the docs check; `docs/` is the Nextra site and `sites/skills` the landing, neither ships in
+the package.

package/README.vi.md

@@ -0,0 +1,43 @@
+# @starci/skills
+
+StarCi Skills là runtime `.claude` của một repository: một cửa vào (`SKILL.md`), mười bốn operator, tám
+workflow ví dụ, một bản đồ routing đóng và một sổ tool. Agent trong Claude Code hay Codex đọc
+`.claude/INDEX.md` qua một đoạn bootstrap ngắn rồi theo đúng thứ tự nạp của nó; phần còn lại là việc của
+cây. Tài liệu: <https://harness.starci.org/docs/vi>. Bản tiếng Anh là thẩm quyền khi chạy: [README.md](README.md).
+
+## Cài đặt
+
+```bash
+npx @starci/skills init
+```
+
+Chạy ở gốc repository sẽ sở hữu runtime. Lệnh chép cây vào `./.claude`, viết `CLAUDE.md` (Claude Code
+đọc) và `AGENTS.md` (Codex đọc) khi chưa có, và thêm `.worktrees/sessions/` vào `.gitignore` vì phiên
+làm việc nằm ở đó. Hãy commit `.claude/` cùng repository: nó là source, không phải cache. Cần Node 20
+trở lên; CLI không có dependency.
+
+| Lệnh | Việc nó làm |
+| --- | --- |
+| `npx @starci/skills init [--dir <repo>] [--force] [--no-bootstrap]` | Cài cây và hai bootstrap. Từ chối một `.claude` đã có sẵn mà không do nó cài, trừ khi `--force`, và kể cả khi đó cũng chỉ thay các đường dẫn runtime. |
+| `npx @starci/skills update [--dir <repo>] [--force]` | Nâng cây đã cài lên phiên bản của gói. File đã sửa tay được giữ lại và liệt kê; `--force` lấy bản của gói. File ngoài các đường dẫn runtime không bao giờ bị đụng. |
+| `npx @starci/skills doctor [--dir <repo>] [--quick]` | Chạy chính bộ validator của cây trên bản đã cài (routing, alias, operator, workflow, mặc định, template, trích dẫn knowledge, self-test của operator và spec của script) và báo những file đã đổi từ lúc cài. |
+| `npx @starci/skills version` | In phiên bản gói. |
+
+Các đường dẫn runtime là `INDEX.md`, `INDEX.vi.md`, `SKILL.md`, `SKILL.vi.md`, `routing.json`,
+`alias/`, `knowledge/`, `operators/`, `readiness/`, `resources/`, `scripts/`, `templates/`,
+`workflows/`. Manifest `.claude/.starci-skills.json` ghi phiên bản đã cài và hash từng file; `update` và
+`doctor` đọc nó.
+
+## Claude Code và Codex
+
+Hai runtime vào cùng một cửa. `CLAUDE.md` và `AGENTS.md` mang cùng một đoạn bootstrap: đọc trọn
+`.claude/INDEX.md` và theo thứ tự nạp của nó. Processor chạy từng operator trên profile mà
+`operator.json` của nó ràng (`resources/agents/profiles/openai.json` cho Codex, `claude.json` cho Claude
+Code, ghép cặp trong `resources/orchestrator.json`), và mỗi operator chỉ được gọi những tool mà
+`operator.json` của nó khai từ `resources/tools.json`. File tiếng Anh là thẩm quyền khi chạy; bản `.vi.md`
+dành cho người đọc.
+
+## Phát triển
+
+Repository này chính là gói. `npm test` chạy mọi validator, self-test của operator, spec của script và
+kiểm tra docs; `docs/` là site Nextra và `sites/skills` là landing, cả hai không nằm trong gói.

package/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: starci
+description: Complete one StarCi mission by freezing its scope, selecting the one operator that owns the outcome, and routing between operators on typed results until the outcome is proved or a person must decide.
+---
+
+# StarCi
+
+One entry, fourteen operators, eight example workflows, one closed routing map, one tool registry. This file picks the
+workflow or composes one, selects the first operator, and sequences the rest. It does no work of its own: it never decides a value, writes source, or judges a
+result.
+
+## Setup
+
+1. Freeze one mission scope: the unit, the target, inclusions and exclusions, write roots, external
+   effects, and what will count as proof. Two readings that would change any of those is one focused
+   question, not a guess.
+2. Run `workspace.bind` for any mission that reads or writes routed source. Nothing else may resolve a
+   checkout, and a similar directory name is never route authority.
+3. Look for a workflow first: read the `when` of every example in `workflows/`. A match is run as
+   written, its presets filling `request.json`. No match means composing a chain from the operators'
+   `## Next` tables under the rules `workflows/README.md` states (required inputs produced earlier,
+   no shared write alias inside a step, loops capped, a declared end); a composed chain worth keeping
+   becomes a new example.
+4. Select the first operator of that chain. Read only that operator's `operator.md` and
+   `operator.json`.
+5. Run that operator, end to end, on the one profile its `operator.json` names under `resources`, with
+   only the grants it lists. An operator has no other model, no inherited turns, and no grant the
+   assignment omits.
+
+## Entry
+
+| The request is about | First operator |
+| --- | --- |
+| Which project, checkout, or runtime binding applies | `workspace.bind` |
+| What the product promises, who may have it, what happens when it fails | `business.decide` |
+| System boundaries, data ownership, or the tech stack | `architecture.decide` |
+| Server behaviour, an API contract, persistence, or a job | `backend.source.apply` |
+| Creating, restructuring, or redesigning a page or surface | `frontend.direction.decide` |
+| Which CSS value an already-composed tree takes | `frontend.presentation.resolve` |
+| Writing an already-resolved tree into product source | `frontend.source.apply` |
+| Whether a rendered surface actually holds up | `frontend.surface.audit` |
+| Build, lint, typecheck, coverage, or Sonar | `quality.verify` |
+| Whether a real person can complete a real journey | `uat.verify` |
+| Shipping a release, or recovering one | `release.deploy` |
+| Observability, Sonar service, or a tunnel | `platform.operate` |
+| An educational content unit | `content.generate` |
+| Publishing an approved Git boundary | `git.publish` |
+
+A request that names no owner, or two owners whose scopes differ materially, stops here with one
+focused question naming the competing boundaries.
+
+## The loop
+
+```text
+request/request.json -> validate-request.mjs -> agent writes response/ -> validate-response.mjs + the operator's validate.mjs -> route
+```
+
+Routing reads `response.json` and nothing else:
+
+1. `done` advances the chain to the next step the workflow names; the next branch's `request.json`
+   points at this branch's outputs by explicit path.
+2. `waiting` runs the nested exchange the response awaits (`<exchange>/request` and `response` inside
+   the same branch), then resumes the same agent; sibling branches keep running.
+3. `blocked` reads `stop`, looks the code up in the merged registry (`operators/errors.json` plus the
+   operator's own `errors.json`) for its `domain`, and resolves that domain in `routing.json`:
+   - `operator` invokes the named operator, then returns here;
+   - `resume` re-enters the same operator in a new step, `request.json.resume` naming the blocked one;
+   - `user` stops and reports what the person must decide or publish;
+   - `external` stops and reports what outside the runtime must change.
+   A code whose disposition is `fallback` never blocks: the agent performs the fallback, records it
+   under `## Fallbacks taken`, and continues, unless the code's `unless` param says otherwise.
+
+A response that fails either validator does not route. Prose in `response.md` does not route. Only a
+validated field of `response.json` does.
+
+`routing.json` is closed and checked: every domain an operator's stop codes hand to has exactly one
+route, and no route names a domain no code reaches. A missing route is a build failure, not a
+judgement call.
+
+## Progress
+
+Every operator carries its own resume and fingerprint semantics, so this file holds no progress
+counter and no handoff state. A `resume` route that returns `NO_PROGRESS` means the same input
+reached the same wall: report the wall rather than trying again.
+
+A cycle between two operators is valid only while the progress fingerprint changes. A repeated
+fingerprint, or the same material finding twice, ends the loop and reports the smaller owner.
+
+## Authority
+
+This file grants nothing. Every authority boundary is enforced by the operator's own `operator.md`
+tables and `validate.mjs`, which this file cannot widen:
+
+- `git.publish` has no requirement that can name a force push, a bypassed hook, a reset, a clean, a
+  stash, or a branch deletion; it merges the session branch, pushes non-force, and a conflict is
+  `NON_FAST_FORWARD` for a person.
+- `release.deploy` and `platform.operate` require an `approval`; `release.deploy` runs only on a
+  `quality-verification` input.
+- `uat.verify` runs only with a `requestedBy`, its account record refuses a password field, and its
+  validator rejects a credential-shaped string anywhere in what it writes.
+- `frontend.presentation.resolve` and `frontend.surface.audit` may name only rule identifiers the bound
+  knowledge publishes; `frontend.source.apply` writes only classes in the resolved inventory.
+- A source-writing operator commits only on `session/<sessionId>`; the person's branch is never touched.
+
+If a mission seems to need more than an operator allows, that is the answer, not an obstacle to route
+around.
+
+## Knowledge
+
+Operators bind their own knowledge; this file does not preload it.
+
+| Folder | Bound by |
+| --- | --- |
+| `knowledge/ui/composition/` | `frontend.direction.decide` |
+| `knowledge/ui/presentation/` | `frontend.presentation.resolve` |
+| `knowledge/ui/proof/` | `frontend.surface.audit` |
+| `knowledge/patterns/fe/`, `knowledge/patterns/be/` | `frontend.source.apply`, `backend.source.apply` |
+| `knowledge/grammars/<family>/` | every operator that composes that family |
+
+English `.md` files are the only runtime authority. Same-stem `.vi.md` files are human mirrors and
+never enter a context manifest, a dependency list, a validator input, or an operator binding.
+
+## Orchestration
+
+One invocation of one operator is one agent, created fresh on the profile its `operator.json` names,
+with the aliases its Context table declares and the tools its `operator.json` declares (`@tools/<id>` from `resources/tools.json`, one mode each) and nothing else. `resources/orchestrator.json`
+fixes the rules: at most three agents at once, branches of one step never sharing a write alias,
+dispatch by workflow and `routing.json`, hand-off only through `response.json` fields inside the
+session (`state.json`, `step-N/parallel-M/{request,response}`), a session the orchestrator creates
+first and deletes after `git.publish`. An agent never starts another agent; a nested exchange (a
+critique, a review) is a second fresh agent the orchestrator spawns for a branch that paused with
+`waiting`. `alias/alias.json` is the one place an alias resolves to a location, and `alias/INDEX.md` is
+its readable map by zone (workspaces, grammar, knowledge, worktrees, remote, dynamic); an operator
+reads only what its Context table names.
+

package/SKILL.vi.md

@@ -0,0 +1,128 @@
+# StarCi
+
+Một cửa vào, mười bốn operator, một bảng định tuyến đóng. File này chọn operator đầu tiên và sắp
+xếp các operator còn lại. Nó không tự làm việc gì: không quyết một giá trị, không ghi source, không
+phán xét một kết quả.
+
+## Chuẩn bị
+
+1. Đóng băng một phạm vi nhiệm vụ: đơn vị, đích, phần bao gồm và phần loại trừ, các gốc được ghi,
+   hiệu ứng ra bên ngoài, và thứ sẽ được tính là bằng chứng. Hai cách đọc làm đổi bất kỳ điểm nào
+   trong số đó là một câu hỏi tập trung, không phải một phỏng đoán.
+2. Chạy `workspace.bind` cho mọi nhiệm vụ có đọc hoặc ghi source đã route. Không thứ gì khác được
+   phép tự tìm checkout, và một thư mục trùng tên không bao giờ là thẩm quyền route.
+3. Tìm workflow trước: đọc `when` của mọi ví dụ trong `workflows/`. Khớp thì chạy đúng như đã ghi,
+   preset điền vào `request.json`. Không khớp thì tự ghép chuỗi từ bảng `## Kế tiếp` của các operator
+   theo luật trong `workflows/README.md` (input bắt buộc phải được sinh trước, không chung alias ghi
+   trong một bậc, vòng lặp có trần, có điểm kết thúc); chuỗi tự ghép đáng giữ thì thành ví dụ mới.
+4. Chọn operator đầu tiên của chuỗi đó. Chỉ đọc `operator.md` và `operator.json` của đúng
+   operator đó.
+5. Chạy operator đó, từ đầu tới cuối, trên đúng một profile mà `operator.json` của nó gọi tên dưới
+   `resources`, với đúng những quyền nó liệt kê. Một operator không có model khác, không thừa hưởng lượt nào,
+   và không có quyền nào mà assignment bỏ sót.
+
+## Cửa vào
+
+| Yêu cầu nói về | Operator đầu tiên |
+| --- | --- |
+| Dự án nào, checkout nào, hay binding runtime nào | `workspace.bind` |
+| Sản phẩm hứa gì, ai được hưởng, hỏng thì ra sao | `business.decide` |
+| Ranh giới hệ thống, quyền sở hữu dữ liệu, hay tech stack | `architecture.decide` |
+| Hành vi phía server, một hợp đồng API, lưu trữ, hay một job | `backend.source.apply` |
+| Tạo mới, dựng lại, hay thiết kế lại một trang hoặc một surface | `frontend.direction.decide` |
+| Một cây đã dựng xong lấy giá trị CSS nào | `frontend.presentation.resolve` |
+| Ghi một cây đã resolve vào product source | `frontend.source.apply` |
+| Một surface đã render có thật sự đứng vững không | `frontend.surface.audit` |
+| Build, lint, typecheck, coverage, hay Sonar | `quality.verify` |
+| Một người thật có hoàn thành được một hành trình thật không | `uat.verify` |
+| Phát hành, hay khôi phục một bản phát hành | `release.deploy` |
+| Observability, dịch vụ Sonar, hay một tunnel | `platform.operate` |
+| Một đơn vị nội dung giáo dục | `content.generate` |
+| Publish một ranh giới Git đã duyệt | `git.publish` |
+
+Một yêu cầu không gọi tên chủ nào, hoặc gọi hai chủ có phạm vi khác nhau đáng kể, dừng lại ở đây với
+một câu hỏi tập trung nêu tên các ranh giới đang cạnh tranh.
+
+## Vòng lặp
+
+```text
+request/request.json -> validate-request.mjs -> agent ghi response/ -> validate-response.mjs + validate.mjs của operator -> định tuyến
+```
+
+Định tuyến chỉ đọc `response.json`, không đọc gì khác:
+
+1. `done` đưa chuỗi tới bậc kế tiếp mà workflow gọi tên; `request.json` của nhánh sau trỏ tới output
+   của nhánh này bằng đường dẫn tường minh.
+2. `waiting` chạy cuộc trao đổi lồng mà response đang chờ (`<exchange>/request` và `response` trong
+   cùng nhánh), rồi cho chính agent đó chạy tiếp; các nhánh cùng bậc vẫn chạy.
+3. `blocked` đọc `stop`, tra mã trong sổ gộp (`operators/errors.json` cộng `errors.json` của chính
+   operator) lấy `domain`, rồi tra domain đó trong `routing.json`:
+   - `operator` gọi operator được nêu tên, rồi quay lại đây;
+   - `resume` vào lại chính operator đó ở một bậc mới, `request.json.resume` trỏ về nhánh bị chặn;
+   - `user` dừng và báo người phải quyết hoặc phải publish gì;
+   - `external` dừng và báo thứ gì ngoài runtime phải thay đổi.
+   Mã có cách xử lý `fallback` không bao giờ chặn: agent làm đúng fallback, ghi dưới
+   `## Fallbacks taken`, rồi chạy tiếp, trừ khi tham số `unless` của mã nói khác.
+
+Response trượt một trong hai validator thì không định tuyến. Văn xuôi trong `response.md` không định
+tuyến. Chỉ một trường đã validate của `response.json` mới định tuyến.
+
+`routing.json` là bảng đóng và được kiểm: mọi domain mà mã dừng của một operator bàn giao tới đều có
+đúng một route, và không route nào gọi tên một domain không mã nào chạm tới. Thiếu một route là lỗi
+build, không phải chỗ để phán đoán.
+
+## Tiến độ
+
+Mỗi operator tự mang ngữ nghĩa resume và fingerprint của nó, nên file này không giữ bộ đếm tiến độ
+hay trạng thái handoff nào. Một route `resume` trả về `NO_PROGRESS` nghĩa là cùng một input đụng
+cùng một bức tường: hãy báo bức tường thay vì thử lại.
+
+Một vòng giữa hai operator chỉ hợp lệ khi fingerprint tiến độ còn thay đổi. Fingerprint lặp lại,
+hoặc cùng một finding đáng kể xuất hiện hai lần, kết thúc vòng lặp và báo về chủ nhỏ hơn.
+
+## Thẩm quyền
+
+File này không cấp gì cả. Mọi ranh giới thẩm quyền đều do các bảng trong `operator.md` và
+`validate.mjs` của chính operator thực thi, và file này không nới rộng được:
+
+- `git.publish` không có yêu cầu nào gọi tên được force push, hook bị bỏ qua, reset, clean, stash hay
+  xoá nhánh; nó merge nhánh phiên, push không force, và xung đột là `NON_FAST_FORWARD` cho người xử.
+- `release.deploy` và `platform.operate` đòi `approval`; `release.deploy` chỉ chạy trên đầu vào
+  `quality-verification`.
+- `uat.verify` chỉ chạy khi có `requestedBy`, bản ghi tài khoản từ chối trường password, và validator
+  của nó bác mọi chuỗi có hình dạng credential trong bất cứ thứ gì nó ghi.
+- `frontend.presentation.resolve` và `frontend.surface.audit` chỉ được gọi tên những mã rule mà
+  knowledge được bind có publish; `frontend.source.apply` chỉ ghi class có trong inventory đã resolve.
+- Operator ghi source chỉ commit trên `session/<sessionId>`; nhánh của người không bao giờ bị đụng.
+
+Nếu một nhiệm vụ có vẻ cần nhiều hơn mức một operator cho phép, thì đó chính là câu trả lời, không
+phải chướng ngại để lách.
+
+## Knowledge
+
+Operator tự bind knowledge của mình; file này không nạp trước.
+
+| Thư mục | Được bind bởi |
+| --- | --- |
+| `knowledge/ui/composition/` | `frontend.direction.decide` |
+| `knowledge/ui/presentation/` | `frontend.presentation.resolve` |
+| `knowledge/ui/proof/` | `frontend.surface.audit` |
+| `knowledge/patterns/fe/`, `knowledge/patterns/be/` | `frontend.source.apply`, `backend.source.apply` |
+| `knowledge/grammars/<họ>/` | mọi operator có dựng họ đó |
+
+File `.md` tiếng Anh là authority duy nhất lúc chạy. File `.vi.md` cùng tên là bản đọc cho người và
+không bao giờ vào context manifest, danh sách phụ thuộc, input của validator, hay binding của
+operator.
+
+## Điều phối
+
+Một lần gọi một operator là một agent, tạo mới trên profile mà `operator.json` của nó gọi tên, với
+đúng những alias mà bảng Context của nó khai và những tool mà `operator.json` của nó khai (`@tools/<id>` từ `resources/tools.json`, mỗi tool một mode), không hơn. `resources/orchestrator.json` chốt
+luật: tối đa ba agent cùng lúc, các nhánh cùng bậc không bao giờ chung alias ghi, điều phối theo
+workflow và `routing.json`, bàn giao chỉ qua các trường của `response.json` trong phiên (`state.json`,
+`step-N/parallel-M/{request,response}`), phiên do orchestrator tạo trước và xoá sau `git.publish`. Agent
+không bao giờ khởi động agent khác; một cuộc trao đổi lồng (phản biện, review) là một agent mới do
+orchestrator tạo cho nhánh đang `waiting`. `alias/alias.json` là nơi duy nhất một alias phân giải ra vị
+trí, và `alias/INDEX.md` là bản đồ đọc được của nó theo vùng (workspaces, grammar, knowledge, worktrees,
+remote, dynamic); operator chỉ đọc những gì bảng Context của nó gọi tên.
+

package/alias/INDEX.md

@@ -0,0 +1,104 @@
+# Alias
+
+Every location an operator may read, by alias, grouped by zone. Generated from `alias/alias.json` (the machine registry) and every `operator.json` by `scripts/generate-alias-doc.mjs`; `--check` runs inside `npm test`. An operator reads only the aliases its own `operator.md` Context table names; this page is the whole vocabulary those tables draw from. Resolution takes the longest registered prefix, a sub-path narrows an alias, and a segment in angle brackets is supplied by the invocation.
+
+## Workspaces — the working area
+
+The working area: routed checkouts of the bound project and the declarations, routes, ports, and identity that locate them.
+
+| Alias | Params | Resolves to | Bind | Writers | Bound by | Purpose |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@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 — the package
+
+The @starci/grammar package as the bound app resolves it: the only fact about what a component owns.
+
+| Alias | Params | Resolves to | Bind | Writers | Bound by | Purpose |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@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 — the law
+
+Canonical law in this tree: universal UI law (ui), the family's taste (grammars), code conventions (patterns). Read only; edited by the owner.
+
+| Alias | Params | Resolves to | Bind | Writers | Bound by | Purpose |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@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 — local authority and evidence
+
+Machine-local authority and evidence outside any checkout: business heads, UAT pairs, debts, templates, the shared runtime owner.
+
+| Alias | Params | Resolves to | Bind | Writers | Bound by | Purpose |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@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 — the internet
+
+Internet. Registries, git remotes, image registries, CI runs, object storage. Read through a network; bound by version, digest, or observed head.
+
+| Alias | Params | Resolves to | Bind | Writers | Bound by | Purpose |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@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 — produced inside the session
+
+Produced inside the current session by an earlier step and deleted with the session. Never exists before the run.
+
+| Alias | Params | Resolves to | Bind | Writers | Bound by | Purpose |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@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 | Params | Resolves to | Bind | Writers | Bound by | Purpose |
+| --- | --- | --- | --- | --- | --- | --- |
+| `@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. |
+
+## Friendly segments inside a 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.
+
+| Segment | Resolves to |
+| --- | --- |
+| `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[])` |
+