owfadev 0.0.1 → 0.3.0

package/.meta/docs/mechanics.md

@@ -0,0 +1,180 @@
+# Mechanics in Detail
+
+> Audience: members and contributors who will modify the framework. The authoritative source of mechanical rules is the kernel reference skill and the `.meta/` source code. This document expands the master outline by one level — principles, instance walkthroughs, and hands-on procedures — without copying rule text; where it conflicts with the source, the source prevails. Written 2026-10-04.
+
+## 0. One Source, Five Projections
+
+Each plugin is one directory, living at `.meta/plugins/<id>/`. `PLUGIN.yaml` is the machine-readable body — the manifest. From the manifest, the kernel script mechanically projects into five places:
+
+| Projection | Landing point | Source key | Who reads it |
+|---|---|---|---|
+| AGENTS injection region | `<!-- plugin:<id> v<x> -->` marker block | `inject` | The agent of every session; constitution-level disclosure |
+| check inspection block | the `check-inject` block inside the check command | `checks` | The check command; semantic items |
+| command usage block | the `cmd-inject` block inside each command | `usage`, in consumes order | Command execution sites; write-side rules |
+| registry plugin section | `.meta/protocol/registry.yaml` | `fields` | Commands consulting the field vocabulary before writing pages |
+| skill copy | `.agents/skills/<command>/` | command and connector masters | Deployment-side agents |
+
+The key property is idempotent rebuilding. Hand-editing inside marker blocks is forbidden — a rebuild overwrites; prose outside the blocks belongs to humans. There is no second source of truth: changing a rule means changing the manifest, after which the single command `all` converges everything. The whole class of documentation-drift problems is eliminated wholesale — projections and the body cannot disagree, because they are not two separate things.
+
+Walk through one real sample. In bb-quiz's manifest, `inject:` is a single one-line disclosure stating what the quiz self-test does and where its products land. After `all` runs, that line appears verbatim in the AGENTS injection region inside the `<!-- plugin:bb-quiz v0.2 -->` block. What agents read day to day is the projection; the manifest body is touched only when (un)installing plugins.
+
+## 1. Plugin Shape
+
+One plugin, one directory, three pieces:
+
+- `PLUGIN.yaml` — the manifest, the body
+- `PLUGIN.md` — pure documentation: design summary, Structure, Invariants, Changelog. The why of the design lives here; mechanical commonality belongs to the kernel reference
+- `scripts/check.py` — optional attached audit. Defines `check(ctx)` returning `[{level, message}]`, read-only with zero side effects; the shape is statically validated via AST
+
+Seven required manifest keys, illustrated with real values from bb-quiz v0.2:
+
+| Key | Semantics | Instance |
+|---|---|---|
+| `id` / `version` / `updated` | Identity and version; advance along the changelog without skipping numbers | `bb-quiz` / `0.2` / `2026-10-04` |
+| `depends` | Dependency list | `[bb-track, bb-map]` |
+| `attachment` | Territory declaration: owning means writing, borrowing means read-only consumption | see below |
+| `fields` | The plugin's own page fields; enter the registry's global vocabulary | `quiz`, the exam-paper block mapping |
+| `inject` | The source of the injection-region line; constitution-level disclosure | see the AGENTS bb-quiz block |
+
+Four optional keys. `commands` declares the commands this plugin drives; `usage` is the write-side rule list; `checks` is the inspection rules; `bridge` is the bridge declaration, which only global pieces may hold.
+
+A fifth optional key `inject_tier` (full|member, default full) carries the **tier law** (issue #12 layer discipline): member exits the AGENTS injection region — exposure rides on the family root's roster line, the skill catalog, and on-demand reads of the manifest, and validate requires a member to reach a full-tier domain root through depends. The projected region carries a byte budget (15 KiB), keeping the A layer pointer-dense: pointers and red lines, never procedures or formats (contract in `protocol/experiments.md`).
+
+attachment deserves a closer look. bb-quiz declares three entries:
+
+- `bb/<term>/<course>/notes/testing/` is the exam-paper sub-region, owned by this plugin. Each test run adds a question set plus answers; grading is appended on the answer page
+- `wiki/bb/<term>/<course>/user.md` is the cognition profile, owned by bb-track. This plugin reads it only; grading writes back through bb-track's write rules
+- `courseware/` and `assessments/` belong to bb-map. This plugin reads them only, taking sm-N anchors, the terminology table, and known assignments
+
+The first is ownership; the latter two are borrows: the territory belongs to another plugin, and write paths must pass through its rules. attachment is the framework's property registry. Who owns which paths, who read-only consumes whom — visible at a glance, mechanically checkable.
+
+## 2. Dependencies and Injection Order
+
+`depends` declares dependencies. validate checks two things: dependencies exist, and there are no cycles — cycles are detected via DFS.
+
+A domain piece is any plugin whose depends chain reaches `domain`. Those connecting to domain directly are domain bases — the five pieces vault, lark, project, email, bb; pieces inside a domain belong to it transitively, without connecting directly. bb-quiz does not connect to domain directly: it arrives via `bb-quiz → bb-track → bb-map → bb → domain`, and is thus a domain piece.
+
+Injection order = dependency topology plus alphabetical order within a batch: dependees are injected first; same-batch pieces sort by name. Look at the bb family's depends and the real order in the injection region:
+
+| Plugin | depends | Effect |
+|---|---|---|
+| bb | `[domain, wiki, trust, log]` | Domain base, injected first within the family |
+| bb-map | `[bb, wiki]` | Mapping law, after bb |
+| bb-track | `[bb, bb-map, trust, wiki]` | Cognition profile, after bb-map |
+| bb-quiz / bb-teach | `[bb-track, bb-map]` | Collection channels; same batch sorted by name — quiz before teach |
+
+This guarantees one thing: when a consumer-side plugin is injected, the disclosures it consumes are already present. bb-teach's injection line says "discipline, see the bb-track block" — that block is necessarily above it. There is one more domain discipline: a domain must be discoverable inside the wiki, via declaration page or injection line; domain pieces create no root containers.
+
+## 3. Projection Walkthrough
+
+Suppose you want to add one discipline to bb-quiz's write-side rules — here is what happens:
+
+1. Edit the `usage:` list in `.meta/plugins/bb-quiz/PLUGIN.yaml` and add a line. While at it, bump `version` and refresh `updated`; add a line to PLUGIN.md's Changelog
+2. Run `python .meta/scripts/wiki_plugin_kernel.py all`. In sequence: validate goes first — failure blocks, fix and rerun; if the inject line changed too, the AGENTS injection region is rebuilt; the cmd-inject blocks of the two command SKILL masters bb-quiz and bb-track are rebuilt — the usage appears in every command whose consumes includes bb-quiz; the registry plugin section is rebuilt; skill copies are synced
+3. Self-review the diff. Changes should land only in the manifest, the two command SKILL masters, and the `.agents/skills/` copies; if inject or fields changed, AGENTS and registry change as well. Any change beyond these is an anomaly
+4. Commit in the format `plugin: bb-quiz …`; one commit does one thing
+
+This is the everyday feel of "one source, five projections": you wrote one thing, and five places agree automatically.
+
+## 4. Command Binding
+
+owner and commands are mutual declarations. A command's SKILL.md frontmatter writes `owner: <plugin-id>`, or `framework` to mean explicitly ownerless; a plugin manifest writes `commands: [command names]`. A one-sided declaration on either side is a validate error — preventing unowned commands and plugins falsely claiming commands alike.
+
+Usage lands on commands by two routes. **Pull side**: a command's frontmatter writes `consumes: [plugin list]`, declaring which plugins' usage it pulls; owner-driven commands must fill it in and include all owners. **Source-side routing**: a plugin manifest writes `usage_routes: [command name list]`, declaring which additional commands its usage lands on — installing the plugin lands the projection, with no need to edit destination commands. Presence-as-registration is honored on the push side: (un)installing a single file takes effect. validate checks that routing targets are present, that routing plugins carry usage, and that duplication with consumes is an error.
+
+Disclosure order is presentation order: owner blocks first, in consumes order; routed blocks in the middle, in dependency topology plus alphabetical order; the remaining consumes bring up the rear.
+
+First-case walkthrough: the bb-track command, this cognition hub. The bb-track command declares only `consumes: [bb-track, trust, log]`; bb-teach and bb-quiz each declare `usage_routes: [bb-track]` in their manifests. After `all`, the bb-track command's SKILL.md contains five `<!-- usage:<id> -->` sub-blocks: bb-track's own write rules, the full usage of the two collection channels bb-quiz and bb-teach, and the write-side rules of trust and log. The effect: any agent stepping into the bb-track command site gets — in one place, with zero retrieval — how teaching and quizzing are used, how grading flows back, and what to do after writes. To establish a third collection channel later, the new plugin only needs well-written usage plus a routing declaration; the projection arrives automatically and the hub command changes not one character.
+
+Usage routing is inspectable at any time via `ls`: every plugin carrying usage lists the commands it lands on; those with no landing are marked as the contract-documentation surface — e.g. email's write-side contract, declared ahead of use.
+
+## 5. The Bridge Law
+
+Global pieces are cross-cutting services and destinations: trust, log, todo, calendar, notes, user-profile. They may declare bridges; a domain piece holding a bridge is an error.
+
+A must-attach bridge is written in the manifest as `bridge: 必依`: every domain base must have a depends edge to the piece; a missing edge is a validate error. log is an instance — the `log` edge in bb's depends in the section 2 table is forced by the must-attach bridge: any domain's activity must leave a trace. This is a topology-completeness invariant, not a style suggestion.
+
+An on-demand bridge is written as `bridge: 按需`: absence is tolerated. user-profile's cognition bridge is an instance — bb-track registers one line only if the profile is present when it creates the archive; if absent it skips, creating nothing on the profile's behalf and raising no error.
+
+Why consumes cannot replace bridges — the 2026-10-04 ruling gives two hard reasons:
+
+1. Must-attach completeness checking is a topological constraint. "All five domain bases, not one may lack an edge" is a global graph invariant; consumes is a single command's list and cannot express global completeness
+2. Writes across territories happen in every command execution. todo derivation, calendar derivation, notes emergence — none of them pass through some single-point command container; there is nowhere to hang consumes
+
+Division of labor: the bridge holds validation and declaration — who may attach, cardinality, completeness checking, absence tolerance; disclosure distribution belongs to projection — the authoritative source of the integration format is usage, arriving at consumption sites via cmd-inject.
+
+## 6. The Derived Layer
+
+The kernel governs the framework area — plugins and projections; pipeline governs the data area — wiki derived pages. The commands are `python .meta/scripts/pipeline.py index / tags / hot / log / verify`:
+
+- **index / tags**: directory indexes and the tag reverse index. Pure-function rebuilds that only aggregate, never inventing structure; when an index list overflows the window, split the subdirectory into its own index — the cure is more subdirectories, not editing the index
+- **hot**: the recent-change hot cache. At most 25 entries, within 5 days, each entry under 200 characters; agents read it first on entering the vault
+- **log**: run-log line writing and rolling archive. Window at most 100 entries; overflow is mechanically archived to `wiki/archive/<month>/log.md`
+- **verify**: post-write consistency check. The post-write pipelines of commands like map and save end with it
+
+Derived pages and projections are two applications of one philosophy: projections derive from manifests — no second source on the framework side; derived pages derive from vault content — no second source on the data side. Hand-editing a derived page is futile; the next rebuild overwrites it.
+
+## 7. (Un)install Lifecycle
+
+The semantic flow of (un)installing goes through the plugin command, where the agent does the semantic part; the mechanical steps are this CLI. Since the split (2026-10-12) **packages are the install unit and this lifecycle is kernel-driven** — the authoritative accounts live in [packages.md](packages.md) (package model, the migrations algebra, the uninstall contract) and in `.meta/command/plugin/SKILL.md` (the wizard protocol). What follows is the historical per-plugin flow, retained for the record; the install steps still describe authoring a new plugin inside the framework repo.
+
+Install, five steps: prepare the three pieces under `.meta/plugins/<id>/`; `validate` — errors block; `all` — projections arrive; smoke test — `audit <id>`, plus a walk-through of the key flows per PLUGIN.md; log a plugin line.
+
+Upgrade, three steps: edit the plugin, bump `version`, add a Changelog line; `all`; log line. Package-level upgrades (`kernel upgrade`) additionally stage semantic migrations — see packages.md.
+
+Uninstall: superseded by the package-level `kernel uninstall <pkg> --yes` (four-clear + residual scan + teardown staging, see packages.md). The old per-plugin flow — `validate` blocks dependents → move the directory out (archived, physical deletion belongs to humans) → `all` — applied before packages existed.
+
+Discipline: script errors always block, warnings only report; versions advance along the changelog — no pre-reserving or skipping numbers.
+
+## 8. How Domains Grow
+
+The framework sets no whitelist for information sources outside the wiki. Integration is answering the same contract, and growth follows the same path. Follow the bb family through — it is the most complete family.
+
+### The Contract's Six Questions
+
+Designing a domain is answering the questions one by one. The answers land in the domain base's territory declaration and injection line:
+
+| Question | The bb family's answer |
+|---|---|
+| Where is the external territory | bb.cuhk.edu.cn, connector bb-cli purely read-only |
+| Landing strategy | Isomorphic two sides: `bb/` workspace plus `wiki/bb/` territory |
+| Identity proof | Term-name and course-code directories, plus machine ids in the bb block mapping |
+| wiki-side territory | `wiki/bb/<term>/<course>/`, bb-map's four-bucket projection |
+| Write model | Fetched artifacts append-only; notes/ human-led, ai products append-only without overwrite |
+| Trust model | machine-confirmed ceiling; stale_after = fetch date + TTL |
+
+### Three Write Models
+
+Landing is essentially a write-model choice, with three archetypes:
+
+- **Final-state asset → append-only store**. Once landed, the body no longer changes — e.g. vault assets, bb materialized courseware. The command side is append-only; deletion and modification belong to humans
+- **Process container → full read-write**. The agent works inside it — e.g. `projects/`, ai products in bb notes/
+- **Truth lives elsewhere → pointer**. The source changes and no local copy is needed — e.g. lark pointer pages, bb media defaulting to pointers. stale_after governs freshness; the agent is the synchronizer
+
+### Projection Density
+
+Projection density decreases as translation cost rises, in three grades. **Mirror**: a 1:1 proxy, e.g. mapping. **Pointer**: token plus url plus snapshot excerpts, e.g. lark. **Disclosure-only**: one injection line plus on-demand live pulls, e.g. email retrieval. The default posture is borrowing vault or pointers; self-standing containers are the exception — when: the write model forks, or the structure is rigidly dictated by the source. bb stands alone for its rigid two-sided structure.
+
+### The Growth Path
+
+After the contract: the **domain base** establishes the territory — bb is isomorphic two sides plus notes/ cohabitation; the **in-domain piece family** follows — bb-map's projection law, bb-track's cognition profile, shapes growing heavier; **consumer-side collection channels** close it out — bb-teach and bb-quiz, zero territory, pure workflow, usage hung on hub commands via source-side routing. The in-family dependency chain `bb-quiz → bb-track → bb-map → bb` is the mechanical expression of this path — see section 2.
+
+### Material and Archives
+
+A two-way split inside the domain. Process products live in the domain workspace: fetched artifacts, human notes, ai notes, exam papers and grading. Settled conclusions live in the wiki territory: projection pages, cognition readings. The wiki takes distillates, not process. This line is isomorphic to the global discipline, only landed inside the domain.
+
+### Connectors
+
+Connectors live in `connectors/` — the domain's deployment-side CLI de-facto interface plus usage disclosure: `connectors/<name>/SKILL.md` lands as the `.agents/skills/` copy via kernel `deploy`. The difference from commands: commands are pure wiki operations, masters in `.meta/command/`; connectors are data-fetching channels to external systems — credentials stay on the local machine, never committed, never persisted to disk. Domain plugins declare territory and discipline; connectors provide the de-facto interface. Discipline and tooling are separate.
+
+## 9. Scenario Quick Reference
+
+| You want to | Action |
+|---|---|
+| Change write-side rules / inspection rules / the injection line | Edit the corresponding manifest key, run `all` |
+| Attach a new plugin's usage to a command | That plugin's manifest writes `usage`; the command's frontmatter consumes adds the id; run `all` |
+| Edit a connector skill | Edit the `connectors/*/SKILL.md` master, run `deploy` or `all` |
+| Quick health check | `validate` plus `audit`; full audit via the check command |
+| (Un)install a plugin | The plugin command does semantics, this CLI does mechanics |
+| Rebuild data-area derived pages | `pipeline.py index` or `tags`; hot and log are maintained as writes happen |
+| Integrate a new external source | Answer the contract's six questions, see section 8; write a connector; the plugin command installs the domain base and in-domain pieces |

package/.meta/docs/naming.md

@@ -0,0 +1,113 @@
+# The name
+
+> **OWFA — One Workspace For All (agents).**
+> Public framework: **OWFA Core** (proposed; `vault-wiki` retires from the public surface) · installer: **OWFA CLI** · GitHub: **owfadev** · npm: `owfa` (application pending) or `owfadev` (fallback).
+
+This page exists because a name is a contract with the people who type it. It records what the words commit to, which layers must not be collapsed, where the name actually resolves, and what happens if a registry refuses the string.
+
+## The line
+
+Use the expansion exactly as written. Do not expand it as *One Wiki For All* or *One Web For All* in any public text — the first is a different (smaller) claim, the second belongs to an unrelated GitHub organization. When the acronym has to stand alone, pair it with the parenthetical once per document, then use `OWFA`.
+
+- 中文：**一个工作区，装下你所有的 agent。**
+- 一句话：OWFA gives every agent you use one workspace to re-enter — your assets, your wiki, your instructions — instead of re-introducing yourself every session.
+- Agent-facing: "This is an OWFA workspace: `vault/` holds real assets, `wiki/` holds the md world, `.meta/` + `.agents/skills/` are the framework body. Read AGENTS.md, then work from the indexes."
+
+## What each word commits to
+
+**One** — one directory, one place a new session re-enters. Not one app that swallows every tool, and not one vendor account. The unit is a workspace the human owns and every agent reads.
+
+**Workspace** — the outer object: `vault/` + `wiki/` + `AGENTS.md` + the framework body. The wiki is the *inner* markdown world; the workspace is what the user actually owns, moves, backs up, and points agents at. Naming the workspace rather than the wiki is deliberate: the contribution is the re-entry surface, not markdown as a format.
+
+**For all (agents)** — all *your* agents: across harnesses (ZCode, Claude Code, Cursor, dsh…), across sessions, across time. It does **not** mean all people, all data, or a hosted service. The parenthetical is part of the name, not a footnote — it is what keeps the claim true. Humans stay the owner and the audit anchor; agents are the ones that re-enter with zero priors.
+
+The name answers the project's actual starting pain: an agent that must be re-introduced every session. "One workspace for all agents" is that pain inverted.
+
+## Layers — do not collapse them
+
+| Layer | Name | Lives in | Job |
+|---|---|---|---|
+| Product | **OWFA** | README, npm page, docs | the brand |
+| Framework | **OWFA Core** (proposed) | `.meta/` + `.agents/skills/` | the body that is installed into a workspace |
+| Installer | **OWFA CLI** | `bin/owfa.js` (npm package) | fetch the tree, `init`, `upgrade`, `doctor`, `add` |
+| Engine | **kernel** | `.meta/scripts/wiki_plugin_kernel.py` | validate / inject / registry / deploy / install mechanics |
+| Plugin tier | **core** | `.meta/plugins/core/` | the 21 framework plugins |
+| Extension | **package** | `.meta/plugins/domains/<pkg>/` | domain families (cuhksz, lark, email, bili, project…) |
+| Unit | **instance** | the user's directory | a deployed workspace |
+
+The call chain is the reason the names must stay distinct:
+
+```
+npx owfa init
+  └─ bin/owfa.js            CLI: fetch payload, copy trees, write AGENTS.md, call the engine
+       └─ kernel             validate → inject → registry → deploy
+            └─ core plugins  the structural contracts projected into AGENTS.md
+```
+
+Two rules fall out:
+
+- **CLI ≠ kernel.** The CLI is replaceable delivery (npm today, pipx or curl tomorrow); the kernel is deterministic mechanics with a fixed contract. Renaming the kernel to "OWFA CLI" would collapse the two and make the npm channel appear to own semantics it does not own.
+- **`core` is the plugin tier.** If the framework is publicly called *OWFA Core*, do **not** also name the repository `core`: one word, two referents. The repo is `owfadev/owfa` for now; if it ever splits, `owfadev/core` (framework body) and `owfadev/cli` (installer) can take the word, and only then does `core` mean the repo.
+
+`vault-wiki` is retired from the public surface: public copy says OWFA (or OWFA Core), the repo target is `owfadev/owfa`. The old string survives in history, old links and technical identifiers; there is no big-bang rename of the kernel, plugin directories or package IDs.
+
+## Two names, two jobs
+
+| Name | Job | Where it appears |
+|---|---|---|
+| `vault-wiki` | historical / technical alias — what the code was called | old links, commit history, registry rows until the move |
+| OWFA / OWFA Core | public name — what the project is | README first line, npm page, docs |
+| `owfadev` | namespace — where the name resolves | GitHub org, npm fallback package |
+
+A name that exists only in slides is a slogan; a name that resolves in a package manager is an address. The address layer is the one that has to be settled mechanically, not rhetorically.
+
+## Namespaces — the actual collision
+
+- **GitHub `owfa` is taken** by an unrelated, dormant organization ("One Web For All", 0 public repos). We do not claim it, link it, or wait for it.
+- **GitHub `owfadev` is available** (checked 2026-10-25). It is the project's org target. The repository target is `owfadev/owfa`; the current `AIE3905-Wuwa/vault-wiki` stays in place until the org exists and the team agrees to the move. A move is a migration either way: transfer the repo into a new org, or rename the current org (`AIE3905-Wuwa` is project-only — 9 repos, 3 members — so renaming is viable if the course no longer depends on the name). Both paths need the same URL/registry sweep; renaming releases the old org name and 404s the old org profile/API, while transferring leaves the course org intact. **Update 2026-10-26: the team agreed — direct org rename (plan B) to `owfadev` with the repository renamed to `owfa`; execution follows `migration.md`.**
+- **npm `owfa` is frozen.** `npm view owfa` returns 404, but 404 means "no published package", **not** "publishable": npm holds the name back under its similarity policy (too close to `ow` / `ora`; reported by the maintainer when publishing). The only path is an application to npm support.
+- **The fallback is `owfadev`** — it returns 404 on npm (no published package, no freeze reported; unlike `owfa`, confirm at the first publish), matching the GitHub org. The package can expose both bins (`owfa` and `owfadev`), so `npx owfadev init` works today and `owfa init` works after a global install. If the application is granted, `owfa` becomes the primary package; `owfadev` stays as an alias or is deprecated, never deleted.
+
+A 404 is not a claim. A frozen name is claimed by an application **plus** a working fallback, not by announcing the command early.
+
+## Sequence — why GitHub first
+
+1. **Create `owfadev` and move the repo** (`owfadev/owfa`), update metadata and links. This is the public home a reviewer can inspect.
+2. **Apply to npm** with the org, the repo, the docs and the fallback as evidence that this is a project, not a typo-squat.
+3. **Publish the fallback first if the application is slow**; switch the primary package to `owfa` if and when it is granted. The brand never blocks on the registry string.
+
+The order is not bureaucratic: npm support evaluates a project by its public home, and a repo that is about to move is weak evidence. Settle the home, then ask for the address.
+
+## What OWFA is not
+
+- Not a SaaS or hosted product; every workspace is local and the framework has no telemetry.
+- Not "for all people" and not a claim of access to all data; the scope is *your* workspace and *your* agents.
+- Not the GitHub org named `owfa`, and not affiliated with "One Web For All".
+- Not a replacement for the kernel, the CLI, or the `core` plugin tier as separate concepts.
+
+## Objections, answered
+
+1. **"It overclaims — it sounds like a universal product."**
+   The scope is bounded twice: *your* workspace, *your* agents. The docs never say all data or all people. A slogan fails when it cannot be falsified; this one has a mechanical test — install it and see whether a fresh agent re-enters without being re-introduced.
+
+2. **"'Workspace' is vague; the thing is a wiki."**
+   The wiki is the medium; the workspace is the owned unit of re-entry. The product's value is that a new session knows where to look, not that files end in `.md`.
+
+3. **"The GitHub org is taken and npm froze the name, so the name is not ours."**
+   The brand and the address are separate. The org target `owfadev` is ours; the npm fallback `owfadev` is publishable; `owfa` is an application, not a dependency. If the string is denied, the project still ships, and the README says which command works.
+
+4. **"Then rename the repo and all packages."**
+   No. The repo target is `owfadev/owfa`; package IDs, plugin directories and the kernel stay as they are. `core` stays the plugin tier. This is the `ripgrep`/`rg` pattern at the namespace level.
+
+5. **"It is still just a slogan."**
+   It is a CLI with a working fallback channel; the command runs under `owfadev` even before `owfa` is granted. That is the difference between a position paper and a channel.
+
+## Where the name is enforced
+
+- `package.json` — `"name": "owfa"` (target) with `"bin": { "owfa": "bin/owfa.js" }`; the fallback is the same file with `"name": "owfadev"` and bins `owfa` + `owfadev`
+- `README.md` — first line, the *Name* section, and the install note (never announce a command the registry does not serve)
+- `templates/AGENTS.template.md` — the identity paragraph a new instance starts from
+- `.meta/docs/distribution.md` — the channel's version invariant, fallback and release runbook
+- `scripts/verify-release.js` — the release gate (name/bin agreement, version rides `.meta/VERSION`, tag matches)
+
+Update 2026-10-26: the repository itself is renamed to `owfa` (`owfadev/owfa`), and the public copy uses OWFA / OWFA Core; `vault-wiki` survives only in history and old links. Nothing in the kernel, plugin IDs, or registry depends on the brand.

package/.meta/docs/packages.md

@@ -0,0 +1,130 @@
+# Packages
+
+> Design record of the split-improvement phase (2026-10-12 → 10-13: binding round issue #20, discovery/download/update, teardown). Mechanism and — more importantly — the reasons behind each decision. Authoritative mechanics live in the kernel (`wiki_plugin_kernel.py`) and in the `PKG.yaml` declarations; this page explains why they are shaped this way.
+
+## Layout: directory == package
+
+`.meta/plugins/` is two-level:
+
+```
+.meta/plugins/
+├── core/            # 20 framework plugins (the two roots + cross-cutting pieces)
+│   ├── wiki/ …
+└── domains/         # one directory per package = the install unit
+    ├── cuhksz/      #   PKG.yaml + 8 plugin masters
+    ├── lark/        #   PKG.yaml + 4 plugin masters
+    ├── email/  bili/  project/
+```
+
+The **directory boundary == tier boundary == package boundary** — the same structure fact expressed once. Projections stay id-keyed and flat (`.meta/command/`, `.agents/skills/`, registry, the AGENTS injection region): packages regroup masters, not projections, so deploy/inject/registry needed no redesign.
+
+| Unit | Members | Connectors | Depends |
+|---|---|---|---|
+| framework (core) | 20, incl. the explicit vault/mapping/structure exception — the default domain is constitutional infrastructure, the mapping proxy layer belongs to the wiki body | — | — |
+| cuhksz | cuhksz · bb · bb-map · bb-track · bb-teach · bb-quiz · sis · registry | bb-cli, sis-cli | framework |
+| lark | lark · lark-docs · lark-im · lark-calendar | lark-cli (external) | framework |
+| email | email | mail-cli | framework |
+| bili | bili | bili-cli | framework |
+| project | project | — | framework |
+
+Why the vault-exception matters: a naive "all domains are packages" split would ship the default domain out of the framework — but every instance boots on vault/mapping/structure before any package exists. Exceptions are declared, not discovered.
+
+## PKG.yaml
+
+```yaml
+schema_version: 1
+id: cuhksz
+version: 0.1            # release ordinal, rides the git tag — NOT tied to member versions
+compat: ">= 0.2"        # framework version floor, checked against .meta/VERSION
+members: [cuhksz, bb, bb-map, bb-quiz, bb-teach, bb-track, sis, registry]
+connectors:             # tri-state:
+  - name: bb-cli        #   in-repo: path (code ships with the package)
+    path: connectors/bb-cli
+  - name: lark-cli      #   external: maintained outside (declaration only)
+    external: true
+  - name: gh            #   system: a preinstalled binary (capability + version expectation, no code)
+    system: true
+    expect: ">= 2.0"
+depends: [framework]    # v1 flat graph — no package-to-package edges
+uninstall:              # declaration, never executable hooks
+  retains: [wiki/cuhksz/, cuhksz/]       # data zones never touched by the kernel
+  credentials: [~/.bb-cli/, ~/.sis-cli/] # prompted, never auto-deleted
+  bridges: [profile#domain-cognition]    # semantic registration points to check
+  processes: []                          # long-running executors to stop
+```
+
+## Invariants
+
+**Authoring side (D1): `members` == the maximal family closure.** The kernel computes the closure (depends chains reaching the package root) and diffs it against the declaration both ways — drift is a validate error.
+
+*Why declare at all, when the closure is computable?* Because **the depends graph is live and a package is a versioned anchor**. A closure-derived package would silently change contents as the graph evolves — the same tag would ship different things at different times. The declared roster pins contents to the version; reconciliation turns structural drift into a commit-time error instead of an install-time surprise. Redundant, but self-verifying — the third application of the owner×commands dual-declaration pattern.
+
+**Site side (D5): v1 requires full presence** — every member on disk. The subset grammar is fixed now so it never breaks the validator later: `installed ⊆ members`, non-empty, dependency-closed, root mandatory. Prunability classes:
+
+| Class | Example | Rule |
+|---|---|---|
+| leaf consumers | bb-teach, bb-quiz | freely prunable — nothing depends on them |
+| structural members | bb, bb-map, bb-track | prunable only together with their dependents (the closure rule enforces it) |
+| family root | cuhksz | never prunable — owns territory, identity page, roster line |
+| connectors | bb-cli | prunable when no installed member consumes it |
+
+`--without` is a reserved parameter (v1 reports not-yet-open). Its promise is semantic — zero injection, zero skill surface, zero credentials — not physical: a cached clone of reviewed code is not an exposure surface, so sparse download stays an optimization outside the contract. Family-root roster lines are capability catalogs; **skill presence is the call-time truth** (tolerant degradation, no dynamic reassembly of inject text).
+
+## Versions (D2)
+
+`.meta/VERSION` anchors the framework (`0.2`, git tag `v0.2`); the kernel contract changes (manifest fields, projection rules) are what bump it. Package versions are release ordinals riding their own tags; **member plugins keep their own changelog versions and the two levels never lockstep** — a package is a distribution unit, not a semantic one.
+
+## Kernel surface
+
+| Command | What it does |
+|---|---|
+| `validate` | full graph + package reconciliation (closure diff, presence, flat graph, compat vs VERSION) |
+| `validate --scope <pkg>` | single-package tolerant mode (D3): deps absent outside the package degrade to warnings — the CI shape for package repos post-split, run with a framework checkout alongside |
+| `pkg` | package inventory: members, connectors, implicit core remainder |
+| `residual <pkg>` | D6 residual scan: greps handwritten AGENTS region + profile/language/calendar/todo/cron anchors for member references (the kernel-managed injection region is skipped — it is cleaned mechanically) |
+| `install <pkg>[@tag]` | resolve the [registry](https://github.com/owfadev/registry) index (members reconciled against PKG.yaml) → trust gate → clone → copy masters/connectors/commands → converge. `install <owner/repo> --yes` installs an unindexed repository (trust: unknown); `--path <dir>` installs a local one (channel C) |
+| `uninstall <pkg> --yes` | D6 four-clear (masters/commands/connectors/skills) + convergence + residual scan + retains/credentials reminders — data never touched |
+| `list-remote` | index table with installed marks |
+| `plan <pkg>` | dependency disclosure before a package lands |
+| `migrate [<pkg>] [--clear] [--force]` | pending semantic migrations: status / clear (author verify + teardown residual gate; use-and-delete) — see [Migrations](#migrations-the-algebra-0--x--y--0) below |
+| `upgrade` | reconciliation report (local vs index); applying runs a **silent reinstall** per package (never cascaded) — member deltas, changelog excerpts, chained migration staging |
+
+*Why scope mode exists before the split:* after the split the framework repo and each package repo no longer contain the full graph — validate would be blind exactly where it matters most. Absence-tolerance turns "plugin missing" from an error into a listed warning, keeping every repo self-checkable.
+
+## Uninstall contract (D6)
+
+No executable uninstall hooks — that would be a **third execution surface** (after inject text and connectors), running at a privileged moment; the security model declines. Instead the package *declares* its deletion semantics (`uninstall:` above) and the flow is: kernel mechanical four-clear (directory / injection / registry / projections) → residual scan output → agent semantic finish per the declaration (credential reminders, process stops, bridge registration lines) behind a confirmation gate. **Data and credentials are never auto-deleted** — the freedom to delete belongs to the human; retained data zones lapse into the deprecated posture.
+
+## Migrations: the algebra 0 → x → y → 0
+
+Package state changes are **semantic migrations carried by declarations, not hooks**. Three kinds close the algebra:
+
+| Kind | Files | Staged when | Lives until |
+|---|---|---|---|
+| init (0→x) | `migrations/init.md` (+ optional `init.py`) | fresh install | verify-clean `--clear` |
+| migrate (x→y) | `migrations/x-to-y.md`, frozen at release | an upgrade landing that version | verify-clean `--clear` |
+| teardown (x→0) | `migrations/teardown.md` | **every install, dormant**; consumed at uninstall | residual-clean `--clear` |
+
+Mechanics: the kernel stages declarations into `.meta/migrations/<pkg>/` (kernel zone — never inside the package dir), keeps a ledger (`pending.json`), and raises the **tri-face warning**: a banner on every kernel invocation · `validate` stays red — mechanical blessing is withheld until the semantic step is done · a kernel-managed block lands in the AGENTS injection region so every session sees it. Clearing runs the author's `verify(ctx)` — AST-gated (read-only, stdlib-only) — then deletes the staged files (**use-and-delete**: declarations are useful precisely once; assertions that hold forever belong in the package's `scripts/check.py` — the judgment split rule).
+
+**Sweep symmetry** keeps the ledger honest without a cron: migrate-kind entries die with the package (uninstall sweeps them), teardown-kind entries die with reinstall (install sweeps them). The dormant `PKG.yaml` copy in the staging directory doubles as a **presence marker**: after a manual `rm -rf` of a package directory, the marker lets the kernel sweep the full mechanical residue — commands, connectors, skills, ledger, banner. Self-healing with no hooks.
+
+**Teardown gate**: teardown declares semantic deletions; with no author script the kernel scans the anchor surfaces (the AGENTS handwritten region, profile / language / calendar / todo / cron pages — the kernel-managed injection region is skipped) for member references — word-boundary, deliberately broad: a layout line naming the territory, a cognition registration line, a calendar source key are all references the human side must finish deleting. Clean anchors clear; hits block `--clear` (override `--force`, on your own judgment). The kernel journal (`.meta/kernel-journal.log`, rolling cap of 500 lines, git-tracked) records the mechanical chain — install / warn+ / clear / uninstall / sweep; mechanical facts only, semantic narrative stays in the instance wiki's log.
+
+## Manifest schema
+
+`schema_version: 1` on PLUGIN.yaml and PKG.yaml. One format migration shared with the upcoming behavior contracts (#34: owns/trigger/emits/never) — versioning the schema once avoids a second format churn when #34 lands.
+
+## Decision ledger
+
+| # | Decision | One-line reason |
+|---|---|---|
+| D1 | declared roster + closure reconciliation | live graph vs versioned anchor; drift → commit-time error |
+| D2 | package version ≠ member versions | distribution unit ≠ semantic unit; lockstep is a trap |
+| D3 | scope/tolerant validate in the binding round | the split is only safe if repos can self-check without the full graph |
+| D4 | instance-local packages live in `domains/` too | one semantic: package directory == install unit; zero-index private packages |
+| D5 | subset grammar fixed now, `--without` opens on demand | validator format never breaks; first real subset user triggers it |
+| D6 | declarative uninstall, no hooks | third execution surface declined; deletion knowledge becomes reviewable data |
+| D7 | migrations are declarations closing 0→x→y→0; teardown ships dormant with every install | semantic change rides reviewable files; the x→0 case must be declared *before* the package is gone |
+| D8 | sweep symmetry + dormant PKG.yaml presence marker | ledger truth without a cron; manual `rm -rf` still self-heals (no hooks anywhere) |
+| D9 | teardown gate = residual scan by default, author scripts optional | D6's no-hooks principle extended to deletion *verification* — zero-script packages still get a semantic gate |

package/.meta/docs/quickstart.md

@@ -0,0 +1,79 @@
+# Quickstart
+
+> The five-minute path. Full guide — components, channels, packages, upgrades, troubleshooting: [deployment.md](deployment.md). The channel's design and release record: [distribution.md](distribution.md).
+> Status: npm `owfa` is under application (frozen on similarity grounds); until the registry serves it, the git channel works today. The fallback package `owfadev` carries the same CLI once published.
+
+## 1. Prerequisites
+
+- **Python 3.9+** — the framework and kernel are pure stdlib; no pip, no venv.
+- **Node 16.7+** — only for the npm channel (the CLI is Node).
+- **An agent** that reads `AGENTS.md` and `.agents/skills/` (ZCode, Claude Code, Cursor, dsh…).
+- **git** recommended — instance snapshots and the upgrade rollback path.
+
+## 2. One command (npm channel)
+
+| Item | Requirement |
+|---|---|
+| Python | 3.9+, pure standard library, zero dependencies |
+| agent | A coding assistant that can read AGENTS.md and `.agents/skills/`, e.g. ZCode |
+| Obsidian | Optional, viewer only |
+
+## Three postures
+
+**0. One command (npm channel).** `npx owfa init <your-vault>` — fetches the framework, creates the directories, writes the AGENTS shell (or appends only the injection region to an existing one), and converges the projections. Then `cd <your-vault> && npx owfa doctor`. This is the same deployment as ①–⑤ below, mechanized; the manual steps remain the reference, the offline path and the developer path. Optional packages: `npx owfa init <dir> --packages cuhksz,lark`; later `npx owfa upgrade` replaces the framework trees and preserves the kernel's migration state. Details: [distribution.md](distribution.md).
+
+The manual steps below serve A and B; posture 0 skips them.
+
+**A. Just using it (clone-as-instance).** A clone of this repository *is* your instance: `git clone https://github.com/owfadev/owfa.git <your-vault>`, optionally `rm -rf <your-vault>/.git && git init` to own the history, then do steps ③–⑤ below (AGENTS.md shell, four directories, converge). Packages install on demand from the registry — `kernel install <pkg> --yes`. No development intent needed; you never touch the framework internals.
+
+**B. Developing (template + instance).** Keep a clone of this repository as the *template* — development, experiments and upstream updates happen there, following [CONTRIBUTING.md](../../CONTRIBUTING.md). Separately deploy a real *instance* (your actual vault — posture A's steps, or the embedding steps below); when the template gains updates, review the diff and sync selectively into the instance, then converge — see the "Template + instance workflow" section of CONTRIBUTING.md. To develop is to run a real instance: the framework is validated in actual use, not in the abstract.
+
+## Five deployment steps
+
+**① Get the framework**: `git clone https://github.com/owfadev/owfa.git`, or download the ZIP and unzip it (the old personal-repo address redirects).
+
+**② Copy two trees** to the target vault root: `.meta/` and `.agents/skills/`. Plugin masters, command masters and copies, protocol artifacts, and mechanical scripts all live there. The clone ships **core 20 only** — no domain packages. Packages are added per need from the registry: `python3 .meta/scripts/wiki_plugin_kernel.py install <pkg> --yes` (see [packages.md](packages.md)); offline alternative — copy a package's `domains/<pkg>/` directory in and rerun `all`.
+
+**③ Write the target vault's AGENTS.md**: draft the shell yourself—one identity paragraph plus a layout description; copy the injection region marker block verbatim from [agents-example.md](agents-example.md), not a single character changed—from `<!-- wiki-inject:start -->` to `<!-- wiki-inject:end -->`—it is the sole source of the structural contract. If the target vault already has an AGENTS.md, paste in only the injection region block.
+
+**④ Create four empty directories**: `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`. Derived pages need no hand-creation—index, tags, hot, and log are built by the pipeline on first run; the root index's `format_version` is also rendered by the pipeline.
+
+**⑤ Converge the projections**, run at the target vault root:
+
+```
+python .meta/scripts/wiki_plugin_kernel.py all
+
+The npm name `owfa` is under application (similarity freeze); until it is granted the fallback package serves the same CLI: `npx owfadev init my-workspace`, `npx owfadev doctor`, etc. — substitute `owfadev` for `owfa` in every command above.
+```
+
+`init` copies `.meta/` + `.agents/skills/`, creates `vault/` and the three wiki directories, writes or appends `AGENTS.md`, and runs the kernel. Existing content is untouched. Optional packages: `npx owfa init my-workspace --packages cuhksz,lark`.
+
+Already have a workspace? `init` refuses if `.meta/` exists; use `npx owfa upgrade` (or `--force` to re-copy the framework trees).
+
+## 3. Manual five steps (git or offline)
+
+1. **Get the framework**: `git clone https://github.com/owfadev/owfa.git my-workspace` — a clone is a valid instance (the pre-rename `AIE3905-Wuwa/vault-wiki` URL redirects). To embed into an existing vault, clone the template elsewhere and copy `.meta/` + `.agents/skills/` into the target root.
+2. **Write `AGENTS.md`**: one identity paragraph, one layout paragraph, and the injection markers verbatim from [agents-example.md](agents-example.md). Existing `AGENTS.md`? Paste in only the marker block.
+3. **Create four directories**: `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`.
+4. **Converge**:
+   ```bash
+   python .meta/scripts/wiki_plugin_kernel.py all
+   ```
+5. **Verify**: drop a file into `vault/`, open an agent at the root, say "map", then "check".
+
+There is no separate kernel install: the kernel is `.meta/scripts/wiki_plugin_kernel.py` inside the tree; Python 3.9+ runs it. On Windows use `py -3` or set `OWFA_PYTHON`.
+
+## 4. Next
+
+```bash
+owfa list                  # registry catalog: packages, versions, installed marks
+owfa add cuhksz            # install a domain package (stops at a semantic migration if one is staged)
+owfa pkg                   # what is installed here
+owfa upgrade               # later: replace the framework trees, preserve instance state
+```
+
+These assume a global install (`npm i -g owfa` or `npm i -g owfadev`); without one, use `npx owfa …` / `npx owfadev …`.
+
+- Package lifecycle, trust levels, offline installs, uninstall: [deployment.md](deployment.md#7-packages--finding-and-installing).
+- Daily use: [usage.md](usage.md); mechanics: [mechanics.md](mechanics.md).
+- Developing the framework itself: [CONTRIBUTING.md](../../CONTRIBUTING.md).