owfadev 0.3.2 → 0.4.0

package/{.meta → .owfa}/docs/packages.md

@@ -1,33 +1,33 @@
 # 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.
+> 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 (`owfa_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:
+`.owfa/plugins/` is two-level:
 
 ```
-.meta/plugins/
-├── core/            # 20 framework plugins (the two roots + cross-cutting pieces)
-│   ├── wiki/ …
+.owfa/plugins/
 └── domains/         # one directory per package = the install unit
+    ├── personal/    #   the embedded suite (21 former core plugins) — installed by a default init
     ├── 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.
+The **directory boundary == tier boundary == package boundary** — the same structure fact expressed once. Projections stay id-keyed and flat (`.owfa/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 | — | — |
+| framework (the channel tree) | none — since the v0.4.0 split the channel ships no plugins (kernel + framework commands only) | — | — |
+| personal (suite) | 21: the former core plugins, incl. the explicit vault/mapping/structure exception — the default domain is constitutional infrastructure, the mapping proxy layer belongs to the wiki body; embedded at `payloads/personal/`, canonical repo **owfa-personal** | — | framework |
 | 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.
+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 other package exists. Since the v0.4.0 split these boot plugins ride as members of the embedded personal suite that the default init installs (exceptions declared, not shipped as framework files).
 
 ## PKG.yaml
 
@@ -35,7 +35,7 @@ Why the vault-exception matters: a naive "all domains are packages" split would
 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
+compat: ">= 0.2"        # framework version floor, checked against .owfa/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)
@@ -72,7 +72,25 @@ uninstall:              # declaration, never executable hooks
 
 ## 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.
+Versioning is **five layers under one principle**: a layer carries release semantics (`A.B.C`) only when a tag or the registry addresses it — the other layers are ordinals or anchors answering *how much has this changed*, not *which release is this*.
+
+| Layer | Version | Semantics | Mechanically consumed by |
+|---|---|---|---|
+| framework / channel | `A.B.C` — `.owfa/VERSION` == `package.json` == tag `vA.B.C` == npm | **A** project status (`0` = alpha) · **B** architecture line (schema / contract / layout — the language `compat` floors speak) · **C** in-line updates | release gate, `upgrade` decision, compat floors |
+| core plugins | `X.Y` | organ revision ordinals — bump on contract or behavior change; with the v0.4 split they are members of the **owfa-personal** package: no release granularity of their own, they ship with the package's `A.B.C` and are addressed by its `personal-vA.B.C` tags | format check (`X.Y`), injection headers, the owfa-personal registry row |
+| packages | `A.B.C` | the domain's own release semantics, independent of the framework (never lockstep) | tags `{pkg}-vA.B.C`, registry rows, migrations |
+| member plugins | `X.Y` | organ revision ordinals, same as core plugins; bump only the members that changed | format check, injection headers |
+| connectors | repo-internal anchors | engineering changelog — never enters registry / tags / PKG version semantics (the kernel never reads it) | none |
+
+**Bump rules** (packages; the framework follows the same semantics):
+
+- **A** moves only at graduation — the owner's call, when a domain's contract (landing strategy / write model / trust model) has survived real use without structural change. Kernel-forced adaptation is **not** an A event: the kernel-generation coupling lives in the `compat` floor (machine-checked), and the forced change classifies as B or C by what it did to the package's own contract.
+- **B** = the domain contract changed: member roster, disclosure / manifest schema, **data or page shape**, trust model, compat floor. B is the only carrier of semantic migrations — migration files are named by B-line pairs (`0.2-to-0.3`) and stage when the upgrade crosses lines (`prev_line <= from_line < new_line`).
+- **C** = updates inside a stable architecture: connector behavior fixes, skill copy, query-side additions. C never carries migrations — **a change that moves data or page shape is B, not C** (the honesty line that keeps C cheap). C is unbounded: `0.3.11`, `0.3.100` — numeric, no letters.
+- The `X.Y` layers keep `X` at `0` while the project is alpha.
+- **C counts releases, not organ changes**: any shipped payload change requires a new release number (a changed tree under an unchanged number is the anchor-equal bug this scheme kills), but organ revisions batch freely — three member plugins of a package changing is one C bump of the owning package, not three. Release cadence is the maintainer's choice; the only invariant is changed-tree ⇒ new-number.
+
+**Sync duties**: framework side — `.owfa/VERSION` == `package.json` == `v`tag == npm == GitHub release notes (the release gate refuses drift). Package side — `PKG.yaml` version == `{pkg}-v`tag == registry row (the kernel refuses drift at install / upgrade), migrations staged by the version pair.
 
 ## Kernel surface
 
@@ -80,9 +98,9 @@ uninstall:              # declaration, never executable hooks
 |---|---|
 | `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 |
+| `pkg` | package inventory: members, connectors, plugins unclaimed by any package (after the core split there is no implicit core remainder — the mechanism remains for loose plugins) |
 | `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 → prospective manifest/budget preflight → copy masters/connectors/commands → converge. `install <owner/repo> --yes` installs an unindexed repository (trust: unknown); `--path <dir>` installs a local one (channel C) |
+| `install <pkg>[@tag]` | resolve the [registry](https://github.com/owfadev/owfa-registry) index (members reconciled against PKG.yaml) → trust gate → clone → prospective manifest/budget preflight → 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 |
@@ -99,7 +117,7 @@ After copying, full binding/bridge/package validation and projection/deployment
 
 The 16 KiB limit and its calculation are unchanged (#48/#49). This does not make `upgrade` transactional: its existing uninstall/reinstall sequence can remove the old package before the install preflight runs. Uninstall's own return-code contract is unchanged.
 
-Offline regression suite: `python -m unittest discover -s .meta/tests -p test_install_preflight.py -v` (synthetic packages; no network or credentials).
+Offline regression suite: `python -m unittest discover -s .owfa/tests -p test_install_preflight.py -v` (synthetic packages; no network or credentials).
 
 ## Uninstall contract (D6)
 
@@ -115,11 +133,11 @@ Package state changes are **semantic migrations carried by declarations, not hoo
 | 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).
+Mechanics: the kernel stages declarations into `.owfa/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.
+**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 (`.owfa/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
 
@@ -138,3 +156,50 @@ Mechanics: the kernel stages declarations into `.meta/migrations/<pkg>/` (kernel
 | 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 |
+
+## Transport contracts (transports block, optional per plugin)
+
+A domain may declare a connector-agnostic capability so that any conforming
+transport — the first-party connector, a third-party one, or a harness-native
+channel — can serve it (work order #56, owfa#27):
+
+```yaml
+transports:
+  contract: qq.transport.v1      # capability id (required)
+  recommends: qq-cli             # default connector (optional; installed under connectors/<id>)
+  declaration: qq/policy.md      # wiki page whose frontmatter `transport:` marks an active third-party transport (optional)
+  providers: qq-cli, napcat-bridge   # comma-separated scalar (minimal-YAML: nested block lists are silently dropped)
+```
+
+Per-provider `harness` / `guarantees` do NOT fit the manifest parser (minimal YAML
+subset — no list-of-maps, review blocker on this PR). They live in two places:
+the contract documentation section below, and the registry row's scalar
+`harness:` field (D1). Guarantee semantics are unchanged: **undeclared =
+guarantee absent** — the agent-side discipline is the floor, transport-side
+enforcement is hardening on top.
+
+`validate` checks the block structurally and judges health mechanically: contract
+declared but neither the recommended connector installed nor the declaration page
+carrying a `transport:` field → warning (unhealthy-but-usable; the domain's skill
+degrades to guidance). Guarantee semantics: **undeclared = guarantee absent** — the
+agent-side discipline is the floor, transport-side enforcement is hardening on top.
+Registry rows may mirror `provides:` / `harness:` for cross-package discovery.
+
+### Contract id grammar
+
+Every contract id follows **`<namespace>.<capability>.v<ordinal>`** — e.g.
+`qq.transport.v1`, `owfa.org.v1`. The namespace is either the declaring package's
+id or the framework-reserved prefix `owfa.`:
+
+- **prefix = declaring package** (mechanically checked): a contract id whose
+  prefix is not `owfa.*` must have its namespace equal the declaring package's
+  id — `validate` rejects anything else;
+- **`owfa.*` is framework-defined**: those names are defined only in the
+  framework repository; the registry review gate enforces this ownership when
+  index PRs are judged;
+- **immutability once published**: a contract name never changes meaning —
+  refining means adding a new name, consolidating means bumping the `v` ordinal
+  (consumers pinned to the old name keep working);
+- **capability matching is exact name equality**: `needs: owfa.org.v1` is
+  satisfied only by `provides: owfa.org.v1` — never by a sibling capability or a
+  different ordinal.

package/.owfa/docs/plugin-lifecycle.md

@@ -0,0 +1,70 @@
+# Plugin Lifecycle
+
+> The third-party developer's view of plugin governance: develop → publish → be found → install → update → uninstall, plus the name-governance rules that keep the ecosystem collision-free. Companion to [packages.md](packages.md) (the package model and its design decisions) and [developer.md](developer.md) (where a plugin lands); this page walks the whole arc from the outside in. **Draft** — scheduled for a dedicated pass in the v0.4.1 docs round; the kernel (`owfa_kernel.py`) and the `plugin` command skill are authoritative where this page and they disagree.
+
+## 1. Develop
+
+One plugin, one directory, three pieces:
+
+- `PLUGIN.yaml` — the manifest, the machine-readable body
+- `PLUGIN.md` — pure documentation: design summary, Structure, Invariants, Changelog
+- `scripts/check.py` — optional attached audit; `check(ctx)` returning `[{level, message}]`, read-only, statically validated via AST
+
+Seven required manifest keys: `id` / `version` (`X.Y` organ ordinal) / `updated` / `depends` / `attachment` (the territory ownership registry: owning vs borrowing) / `fields` / `inject` (the constitution-level disclosure line). Optional keys include `commands`, `usage`, `checks`, `bridge`, `inject_tier` (full|member), `usage_routes`, and the `transports` block (contract id grammar: see [packages.md](packages.md) §Transport contracts).
+
+The manifest is a **minimal YAML subset** — top-level scalars, `key: []`, block lists, one-level block mappings; anything richer is silently dropped, so keep declarations flat.
+
+**The validate gate**: `kernel validate` (or `validate --scope <pkg>` inside a package repo, where out-of-package dependencies degrade to warnings) checks manifest compliance, dependency existence and acyclicity, command bindings, the bridge law, and package reconciliation (`members` == family closure, both directions). Errors block; warnings report.
+
+**One source, five projections**: from the manifest the kernel projects into the AGENTS injection region (`<!-- plugin:<id> v<x> -->` blocks), the check command's inspection blocks, command usage blocks, the registry's field vocabulary, and the `.agents/skills/` copies. Never hand-edit a projection — change the manifest, run `all`, everything converges. The projected region carries a byte budget (16 KiB) and each full-tier inject line a 256 B pointer-density guideline.
+
+## 2. Publish
+
+A plugin never ships bare — the **package is the distribution unit** (a lone plugin is a single-member package; 12 lines of PKG.yaml). Publishing is:
+
+1. Author `PKG.yaml` — `id`, `version` (`A.B.C`, the domain's own release semantics, never lockstep with the framework), `compat` floor (checked against `.owfa/VERSION`), `members` roster, `connectors` (tri-state: in-repo path / external / system), `depends: [framework]`, and the declarative `uninstall:` block (retains / credentials / bridges / processes — declaration, never executable hooks).
+2. Tag the release: `git tag <pkg>-vA.B.C` — the tag, the PKG version, and the registry row must agree; the kernel refuses drift at install/upgrade. The core suite follows the same rule with `personal-vA.B.C` tags (package **owfa-personal**).
+3. Open a one-line PR to the [registry](https://github.com/owfadev/owfa-registry) (`INDEX.yaml`). This PR is the **human-review gate** — inject text and connectors are the security faces, so an index row is earned, not claimed. The PR is also where the trust level is assigned.
+
+Bump rules in brief: **A** only at graduation; **B** = contract change (roster, schema, page shape, trust model — the only carrier of semantic migrations, named by B-line pairs like `0.2-to-0.3`); **C** = in-architecture updates, never migrations; changed tree ⇒ new number, always.
+
+## 3. Be found
+
+- `kernel list-remote` — the registry catalog: package versions, compat floors, member plugins, trust levels, installed marks.
+- `kernel plan <pkg>` — the consent wizard's data source: trust level, package disclosure, baseline/optional members, connectors, suggested command. One-shot and never interactive — the *agent* runs the consent conversation; the kernel only discloses.
+
+## 4. Install
+
+Three channels:
+
+| Channel | Form | Trust |
+|---|---|---|
+| A — registry | `kernel install <pkg>` (optionally `<pkg>@<tag>`) | from the index row: `framework-bundled` / `reviewed-3rd-party` install without a prompt; anything else needs `--yes` |
+| B — unindexed repo | `kernel install <owner>/<repo> --yes` | unknown — `--yes` is the trust gate; the registry PR is how a package earns reviewed trust |
+| C — local path | `kernel install <pkg> --path ./dir` | you reviewed it by hand; no registry involved |
+
+Before copying anything, `install` **stages the prospective masters in a temp directory** with the actual install filter and runs manifest/dependency/budget preflight against the combined (installed + incoming) set — a rejection exits 1 before any file changes. After the copy, convergence (validate → inject → registry → deploy) runs; failure there is *not* transactional — inspect, fix, `kernel validate`. A package declaring a first-run semantic migration (`migrations/init.md`) installs mechanically but leaves `validate` red and a banner up until an agent performs the semantic step and clears it (`kernel migrate <pkg> --clear`).
+
+## 5. Update
+
+- `kernel upgrade` — read-only reconciliation report (local versions vs the index).
+- `kernel upgrade <pkg> --yes` — **silent reinstall** per package, never cascaded: member deltas, changelog excerpts, and chained migration staging. Crossing a B-line stages the corresponding `x-to-y` migration declarations.
+- The framework itself updates through its own channel — npm (`owfa upgrade`) or git re-copy — never through package upgrade.
+
+## 6. Uninstall
+
+`kernel uninstall <pkg> --yes` runs the mechanical **four-clear**: package directory (masters), commands owned by members (masters + skill copies), connectors, and projections (injection region and registry rebuild via convergence). Then:
+
+- **residual scan** — the kernel greps the semantic anchor surfaces (handwritten AGENTS region, profile / language / calendar / todo / cron pages) for member references, word-boundary and deliberately broad; hits are the human-side cleanup list (the kernel-managed injection region is skipped — it is already cleaned mechanically).
+- **reminders, never deletions** — `retains` zones and `credentials` are reported, never auto-deleted; **data zones and credentials are never touched by the kernel**, ever. The freedom to delete belongs to the human.
+- A declared `teardown.md` (staged dormant at every install) flips to a pending warning at uninstall — semantic deletion debt with the same tri-face banner and a residual-gated `--clear`.
+
+## 7. Name governance (three gates)
+
+Collisions are stopped mechanically at three layers:
+
+1. **Plugin id** — `validate` errors on a duplicate plugin id (two layouts declaring it) *and* on install-time duplicates (an incoming package whose member id is already installed is rejected at preflight).
+2. **Package id** — the registry `INDEX.yaml` is keyed by package id; the index PR review is where ownership of a name is decided, before anything is installable by that name.
+3. **Command names** — owner × commands mutual declaration: a command's `owner` frontmatter and a manifest's `commands` list must agree bidirectionally; one-sided claims, ownerless commands (missing `owner`), and framework combined with other owners are all validate errors. Two packages therefore cannot silently ship the same command name.
+
+Transport/capability names follow the same philosophy: the contract id grammar (`<namespace>.<capability>.v<ordinal>`) namespaces every capability under its declaring package (or the framework-reserved `owfa.`), mechanically checked — see [packages.md](packages.md).

package/{.meta → .owfa}/docs/quickstart.md

@@ -24,7 +24,7 @@
 
 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.
+**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 (suite install, AGENTS.md shell, converge, verify). 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.
 
@@ -32,36 +32,36 @@ The manual steps below serve A and B; posture 0 skips them.
 
 **① 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`.
+**② Copy two trees** to the target vault root: `.owfa/` and `.agents/skills/`. Kernel, framework command masters and copies, protocol artifacts, and mechanical scripts all live there. Since the v0.4 split the tree carries **no plugins** — install the embedded personal suite (the 21 former core plugins, shipped in the clone at `payloads/personal/`) right after: `python3 .owfa/scripts/owfa_kernel.py install personal --path <clone>/payloads/personal` — its `skeleton:` declaration creates the four instance directories. Further packages are added per need from the registry: `python3 .owfa/scripts/owfa_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.
+**④ Skeleton comes with the suite**: the personal suite's `PKG.yaml` `skeleton:` created `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/` at install. 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
+python .owfa/scripts/owfa_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`.
+`init` copies `.owfa/` + `.agents/skills/`, writes or appends `AGENTS.md`, runs the kernel, then installs the embedded personal suite — the 21 former core plugins — which declares and creates the skeleton (`vault/` and the three wiki directories) and deploys its commands. 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).
+Already have a workspace? `init` refuses if `.owfa/` 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/`.
+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 `.owfa/` + `.agents/skills/` into the target root.
+2. **Install the embedded personal suite**: `python3 .owfa/scripts/owfa_kernel.py install personal --path <clone>/payloads/personal` — the 21 former core plugins land as a package and the four skeleton directories come with its `skeleton:` declaration.
+3. **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.
 4. **Converge**:
    ```bash
-   python .meta/scripts/wiki_plugin_kernel.py all
+   python .owfa/scripts/owfa_kernel.py all
    ```
-5. **Verify**: drop a file into `vault/`, open an agent at the root, say "map", then "check".
+5. **Verify**: drop a file into `vault/`, open an agent at the root, say "owfa-map", then "owfa-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`.
+There is no separate kernel install: the kernel is `.owfa/scripts/owfa_kernel.py` inside the tree; Python 3.9+ runs it. On Windows use `py -3` or set `OWFA_PYTHON`.
 
 ## 4. Next
 

package/{.meta → .owfa}/docs/research-user-profile.md

@@ -1,6 +1,6 @@
 # User Profile Research Distillation (design basis for user-profile)
 
-> Development-side design archive (2026-09-13, distilled from four rounds of web research): the selection basis for the user-profile plugin. Not a runtime artifact of any instance; framework behavior is sourced from `.meta/plugins/user-profile/`.
+> Development-side design archive (2026-09-13, distilled from four rounds of web research): the selection basis for the user-profile plugin. Not a runtime artifact of any instance; framework behavior is sourced from `.owfa/plugins/user-profile/`.
 
 "User profiling" has two practice lines with different semantics: the product-design line draws **representative fictional target users** (personas), serving design decisions; the agent-memory line maintains **a continuous cognition profile of the real user** (user profile), serving personalization. vault-wiki's profile plugin belongs to the latter—borrowing the dimension framework from the former and the update mechanism from the latter.
 

package/{.meta → .owfa}/docs/sandbox.md

@@ -4,16 +4,16 @@
 
 ## What it is
 
-test-repo is a scratch deployment instance living inside the development repository — **local-only and untracked since 2026-10-13**: a fresh clone of the framework carries none of it, and nothing inside (mirrors included) can enter history. Its `.meta/` and `.agents/` trees are a mirror of the framework, re-copied wholesale from the root side when a batch closes; everything else is the sandbox's own data zone. The inside of the sandbox is unaware of this project: a session opened at the sandbox root reads the sandbox's own AGENTS.md and skills.
+test-repo is a scratch deployment instance living inside the development repository — **local-only and untracked since 2026-10-13**: a fresh clone of the framework carries none of it, and nothing inside (mirrors included) can enter history. Its `.owfa/` and `.agents/` trees are a mirror of the framework, re-copied wholesale from the root side when a batch closes; everything else is the sandbox's own data zone. The inside of the sandbox is unaware of this project: a session opened at the sandbox root reads the sandbox's own AGENTS.md and skills.
 
 ## Enabling it
 
 The sandbox is not initialized in a fresh clone. To set one up (or redo it from scratch), four steps:
 
 1. `mkdir test-repo` at the framework root
-2. Copy the framework trees in: `.meta/` and `.agents/` from the root side
+2. Copy the framework trees in: `.owfa/` and `.agents/` from the root side
 3. Create the `AGENTS.md` shell inside: one identity paragraph plus a layout description, and insert the injection region marker block — from `<!-- wiki-inject:start -->` to `<!-- wiki-inject:end -->`, keeping the region header and the explanatory lines (see [agents-example.md](agents-example.md))
-4. Create four empty directories (`vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`) and run `python .meta/scripts/wiki_plugin_kernel.py all` at the sandbox root — the injection region fills, all-green validate makes it a usable instance
+4. Create four empty directories (`vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`) and run `python .owfa/scripts/owfa_kernel.py all` at the sandbox root — the injection region fills, all-green validate makes it a usable instance
 
 ## Running experiments
 

package/{.meta → .owfa}/docs/usage.md

@@ -37,7 +37,7 @@ The standard flow for changing the framework — see AGENTS "commit flow" for de
 
 **Installing a new domain**, bringing an external source in: `kernel list-remote` shows the catalog; `kernel install <pkg> --yes` lands the package — plugins, commands, and in-repo connectors arrive in one step (the bb course domain brings bb-cli with it; lark declares the external lark-cli; email mail-cli). Credentials stay on the local machine; on first use read the connector skill disclosure, e.g. bb-cli's credentials and usage. The domain growth path and its decision criteria are in the mechanics doc, "How Domains Grow" section.
 
-**Experiments** always land in the test-repo sandbox or locally. Sandbox usage is in `.meta/docs/sandbox.md`; sandbox experiment content never enters history — conclusions travel via conversation reports or docs.
+**Experiments** always land in the test-repo sandbox or locally. Sandbox usage is in `.owfa/docs/sandbox.md`; sandbox experiment content never enters history — conclusions travel via conversation reports or docs.
 
 ## Rhythm
 

package/{.meta → .owfa}/protocol/actions.md

@@ -1,14 +1,14 @@
 # Action discipline: path zones × action tiers
 
-> The semantic shape of permissions: this table does not rely on code for "enforcement", but deterministic structural operations are entrusted to scripts (`.meta/scripts/wiki_plugin_kernel.py`: compliance / dependencies / injection / registry / copy sync; `.meta/scripts/pipeline.py`: index / tags rebuild, hot / log rolling, post-write self-attestation), while semantic judgment is entrusted to the LLM; the agent consults this table before acting, and check audits afterwards from script output and git traces.
+> The semantic shape of permissions: this table does not rely on code for "enforcement", but deterministic structural operations are entrusted to scripts (`.owfa/scripts/owfa_kernel.py`: compliance / dependencies / injection / registry / copy sync; `.owfa/scripts/pipeline.py`: index / tags rebuild, hot / log rolling, post-write self-attestation), while semantic judgment is entrusted to the LLM; the agent consults this table before acting, and check audits afterwards from script output and git traces.
 > Four execution principles: deterministic structural operations go through scripts, semantic judgment through the LLM; rules spell out in plain text "how to do" rather than "what it is"; if one read suffices, there is no second scan (call frugality); write commands must close with `pipeline.py verify` self-attestation (the minimal attester form: the LLM executes, the script attests).
 
 ## Path zones
 
 | Zone | Paths | Nature |
 |---|---|---|
-| Regenerable | `wiki/index.md`, `wiki/tags.md`, `wiki/hot.md`, the `.meta/protocol/registry.yaml` plugins section | Derived projections, wholly rebuildable; the pipeline may rerun freely |
-| Precious | `wiki/notes/**`, `.meta/plugins/**`, `.meta/command/**`, the AGENTS.md hand-written region | Append-only or human-edited |
+| Regenerable | `wiki/index.md`, `wiki/tags.md`, `wiki/hot.md`, the `.owfa/protocol/registry.yaml` plugins section | Derived projections, wholly rebuildable; the pipeline may rerun freely |
+| Precious | `wiki/notes/**`, `.owfa/plugins/**`, `.owfa/command/**`, the AGENTS.md hand-written region | Append-only or human-edited |
 | Immutable | existing entries of `wiki/log.md` and `wiki/archive/**`, `vault/**` (from the command's perspective) | Content must not be rewritten after writing |
 | Workspace | `projects/**` | Full agent read-write authority (in contrast to the append-only vault); the self-describing `project.md` accompanies each project |
 | Temporary | `wiki/tmp/**` | No retention promise, may be cleaned; invisible to the derived layer (index/tags/link graph), exempt from broken-link checks |
@@ -17,7 +17,7 @@
 
 | Tier | Typical actions | How executed |
 |---|---|---|
-| Mechanical-auto | index / tags / registry rebuild, injection-region rebuild, hot window eviction, log archival routing, hash recalculation, query log lines, command copy sync, post-write self-attestation | Execute directly (whatever scripts can do goes through scripts: `wiki_plugin_kernel.py` and `pipeline.py`), no asking |
+| Mechanical-auto | index / tags / registry rebuild, injection-region rebuild, hot window eviction, log archival routing, hash recalculation, query log lines, command copy sync, post-write self-attestation | Execute directly (whatever scripts can do goes through scripts: `owfa_kernel.py` and `pipeline.py`), no asking |
 | Mechanical-confirm | tag merges (batch edits to plugin fields), reserved-field migration, tmp over-age cleanup (present list, delete after confirmation) | Present the list, execute after confirmation |
 | Semantic-report | note-merge suggestions, near-duplicate alerts, staleness judgments on proxy descriptions | Report the differences; the human decides |
 | Always-human | deletion, history rewriting, changes to existing `vault/` files, rewriting note bodies | Commands never execute these; ghost-writing on explicit user instruction must leave a log trace |
@@ -28,7 +28,7 @@ The criterion: touching "plugin-owned fields or regenerable pages" → mechanica
 
 > In this framework git is process-layer infrastructure (version control / audit evidence / lockfile), not a plugin; this section gives the commit rules for data-zone writes—for the engineering side see constitution principle 8; the two domains do not encroach on each other.
 
-- **One write operation = one commit**: one map / save / profile / check fix, together with all its derived products (pages + index / tags / hot / log + new vault assets), enters the commit atomically; commit only after verify passes—what is committed is what has been self-attested; no commit when nothing changed
+- **One write operation = one commit**: one owfa-map / owfa-save / owfa-profile / owfa-check fix, together with all its derived products (pages + index / tags / hot / log + new vault assets), enters the commit atomically; commit only after verify passes—what is committed is what has been self-attested; no commit when nothing changed
 - **Message format `module: summary`** (isomorphic with the engineering side; module word + half-width colon): the data-zone module vocabulary is taken from the commands, defined at this single point and not re-copied into command docs—`map: <asset name>`, `save: <page title>`, `profile: <one-liner>`, `check: <conclusion>`, `query: <topic>`
 - **The agent only adds paths it has written; `git add -A` is forbidden**: commit rights over human hand edits (vault deletions/changes, manual wiki edits) belong to the human—the agent only reports; committing on someone's behalf requires explicit user instruction
 - No pushing; history rewriting is forbidden (constitution principle 8, globally applicable)
@@ -37,6 +37,6 @@ The criterion: touching "plugin-owned fields or regenerable pages" → mechanica
 
 - **log**: main-file window ≤100 entries (about 14k characters). Write log entries via `pipeline.py log <type> "<one-liner>"`—on overflow, the oldest stretch is moved, grouped by entry month, into `wiki/archive/YYYY-MM/log.md`; entry content is unchanged to the character, only relocated; the archive directory falls into the immutable zone
 - **hot**: ≤25 entries, <5 days, ≤200 characters per entry. Write hot entries via `pipeline.py hot <type> "<one-liner>"`—out-of-window entries are evicted and over-long entries truncated automatically before writing
-- **Index / registry**: on deviation from reality → rebuild directly inside check (`pipeline.py index` / `tags`; `wiki_plugin_kernel.py all`), no asking
+- **Index / registry**: on deviation from reality → rebuild directly inside check (`pipeline.py index` / `tags`; `owfa_kernel.py all`), no asking
 - **Vocabulary**: before writing tags, map / save first reads `wiki/tags.md` (the derived zone is the vocabulary), preferring to reuse existing words; near-duplicate merging is a mechanical-confirm item
 - **Parameter ownership**: mechanical parameters such as rolling windows defer to the `pipeline.py` source (the script source is the rule list), while plugin PLUGIN.md files keep the semantic explanations—commands and docs do not re-copy the numbers

package/.owfa/protocol/registry.yaml

@@ -0,0 +1,34 @@
+# owfa Field Registry (protocol artifact, aggregated projection)
+#
+# Rules:
+# - The protocol section is the authoritative source; revisions must pass check
+# - The plugins section is aggregated from the fields declarations of each PLUGIN.yaml; check validates consistency, and on deviation this table is rewritten with PLUGIN.yaml as the authority
+# - The reserved section is a backfill channel: legitimate staging fields, exempt from the ghost check, awaiting a future plugin's claim
+# - map / save read this table as step 0 (one-read anchor: fields and value sets are visible before writing, no full-repo scan)
+# - Fields stack by composition: one page = protocol fields + each plugin's fields (e.g. a source page = protocol + vault + tag)
+# - Actor convention (the unified value format for all attribution fields): human:name (e.g. human:Joss) / process:workflow name (e.g. process:hash-recalc) / agent/model identifier (e.g. agent/GLM-5.3)
+# - Legacy value migration mapping: seed→draft, developing→draft, done→stable
+
+protocol:
+  type:
+    values: [source, session, profile, todo, structure, language, lark, calendar, project, email, bb, tmp]
+    note: "Territory values are closed (extending values requires revising this table)—determines page ownership and mechanical checks: source=proxy page, session=sessions territory, profile=profile page, todo=temporary memory page, structure=structure declaration page, language=language declaration page (wiki/language.md, `language`/`terms` block mappings, owned by the language plugin), lark=external pointer page (wiki/lark/ territory, the token is the identity proof, owned by the lark plugin family), calendar=time territory page (month page, two-section system), project=project declaration page (wiki/projects.md, `projects` block mapping; the project proper lives in the root container projects/), email=personal mailbox domain page (wiki/email/ territory—digest page / people / threads / sources archives, token = email address or Message-ID, owned by the email plugin), bb=BB course domain page (wiki/bb/ territory—domain-root digest page and course identity pages, term_id/course_id is the identity proof, owned by the bb plugin), tmp=temporary page (path is the territory, invisible to the derived layer); import/interop consumer sides tolerate unknown types"
+    defaults: [concept, qa, decision, entity, comparison]
+    defaults_note: "Form defaults vocabulary—knowledge forms within the notes territory, no mechanical semantics; instances extend it freely (no revision of this table required), prefer reuse to prevent vocabulary fragmentation"
+  status:
+    values: [draft, stable, deprecated]
+    note: "Three lifecycle values; deprecated = kept for links and history but no longer current"
+  title:
+    note: "Page title, a string; recommended as a required field"
+  description:
+    note: "One-sentence description (≤80 characters); data source for index entries and viewer hints; when absent, the index takes the first sentence of the body"
+  created:
+    note: YYYY-MM-DD
+  updated:
+    note: "YYYY-MM-DD, refreshed by any write operation"
+
+plugins:
+
+
+reserved: {}
+