owfadev 0.0.1 → 0.3.1

package/.meta/docs/deployment.md

@@ -0,0 +1,311 @@
+# Deployment
+
+> Reader: anyone installing OWFA into a directory (an Obsidian vault, a notes folder, any workspace), or the agent doing it for you. This is the full guide — components, channels, first run, packages, upgrades, troubleshooting. The five-minute path is [quickstart.md](quickstart.md); the channel's design and release record is [distribution.md](distribution.md).
+
+## 1. What gets installed
+
+OWFA has three layers, and only one of them is "installed":
+
+| Layer | What it is | Where it lives | Installed? |
+|---|---|---|---|
+| **OWFA CLI** | the installer / upgrader (`init`, `upgrade`, `doctor`, `add`, `list`, `pkg`) | npm package, run via `npx` or a global install | no — it stays outside the workspace |
+| **OWFA Core** | the framework body: plugins, commands, protocols, kernel, skill copies | `.meta/` + `.agents/skills/` | yes — copied into the workspace |
+| **kernel** | the deterministic Python engine (`validate`, `inject`, `registry`, `deploy`, `install`) | `.meta/scripts/wiki_plugin_kernel.py` | no — it ships **inside** Core; there is no separate kernel install |
+| **packages** | optional domain extensions (course, lark, email, bili, project…) | `.meta/plugins/domains/<pkg>/` | on demand |
+| **instance** | the workspace you own: `vault/`, `wiki/`, `AGENTS.md`, the framework body | your directory | — |
+
+The call chain is one direction:
+
+```
+OWFA CLI  →  copies OWFA Core  →  runs the kernel  →  kernel converges Core + packages
+```
+
+A deployed workspace looks like this:
+
+```
+my-workspace/
+├── AGENTS.md                  # identity/layout (yours) + injection region (kernel-managed)
+├── vault/                     # real assets, any format
+├── wiki/                      # the markdown world
+│   ├── notes/  sessions/  vault/
+│   └── index.md  tags.md  hot.md  log.md   # derived, rebuilt by the pipeline
+├── .meta/                     # OWFA Core
+│   ├── VERSION                # framework anchor (0.3)
+│   ├── scripts/               # kernel + pipeline + wikilib
+│   ├── plugins/core/          # 21 framework plugins
+│   ├── plugins/domains/       # installed packages (empty until you add one)
+│   ├── command/               # command masters
+│   └── docs/                  # this guide and friends
+└── .agents/skills/            # deployed command/connector skill copies
+```
+
+The kernel is **not** a service, a daemon, or a pip package. It is a pure-stdlib Python script that the CLI (and the agent) invoke on demand. Python 3.9+ is the only runtime requirement for Core.
+
+## 2. Prerequisites
+
+| Item | Requirement | Needed for |
+|---|---|---|
+| Python | **3.9+**, pure standard library | Core and the kernel |
+| Node | **16.7+** | the npm channel only (the CLI is Node) |
+| agent | a coding assistant that reads `AGENTS.md` and `.agents/skills/` (e.g. ZCode, Claude Code, Cursor, dsh) | daily use |
+| git | recommended | instance snapshots and upgrade rollback |
+| Obsidian | optional | viewing the wiki; never required |
+
+The framework itself has zero package-manager dependencies: no `pip install`, no Python venv, no npm dependencies in the tarball. `npm` is a delivery vehicle, not a runtime.
+
+## 3. Choose a channel
+
+All channels deploy the same Core tree; pick by environment, not by feature.
+
+| Channel | Command | Status |
+|---|---|---|
+| npm, target name | `npx owfa init my-workspace` | **name application pending** (npm froze `owfa` as too similar to `ow`/`ora`) |
+| npm, fallback name | `npx owfadev init my-workspace` | same CLI, bins `owfa` + `owfadev`; to be published if the name is not granted |
+| git, clone-as-instance | `git clone https://github.com/owfadev/owfa.git my-workspace` | works today |
+| git, embed into an existing vault | clone the template elsewhere, copy `.meta/` + `.agents/skills/` | works today |
+| template + instance (developers) | a template clone + a separate instance | see [CONTRIBUTING.md](../../CONTRIBUTING.md) |
+
+> Until the npm name is served by the registry, the git channel is the working path. Do not treat `npx owfa` as live before `npm view owfa version` returns a version.
+>
+> The org rename executed 2026-10-26 (`AIE3905-Wuwa` → `owfadev`, `vault-wiki` → `owfa`); old repository URLs redirect, old org/API paths 404.
+
+## 4. Install
+
+### 4.1 npm channel — one command
+
+```bash
+npx owfa init my-workspace          # target; once the name is granted
+# or, while the name is pending:
+npx owfadev init my-workspace       # fallback package, same CLI
+cd my-workspace
+npx owfa doctor                     # target: python, framework, markers, kernel validate
+npx owfadev doctor                  # fallback: same check through the fallback package
+```
+
+**Command forms.** `npx <package> <verb>` needs no global install. A global install (`npm i -g owfa` or `npm i -g owfadev`) puts **both** `owfa` and `owfadev` on `PATH`. The rest of this guide writes `owfa <verb>` for the CLI and `kernel …` for the Python engine; substitute `npx owfa` / `npx owfadev` if you are not installing globally.
+
+`init` performs the five manual steps below:
+
+1. copies `.meta/` and `.agents/skills/` from the tarball;
+2. creates `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`;
+3. writes `AGENTS.md` from the seed, or appends **only the injection region** to an existing one (the handwritten part is preserved; half-present markers are refused);
+4. runs `python .meta/scripts/wiki_plugin_kernel.py all` (validate → inject → registry → deploy);
+5. optionally installs packages (`--packages cuhksz,lark`), stopping at the first package that stages a semantic migration.
+
+Useful flags:
+
+- `--name NAME` — the workspace name written into the AGENTS seed;
+- `--packages a,b` — install packages from the registry during init;
+- `--force` — re-copy the framework trees over an existing instance, preserving the kernel's migration ledger, journal and registry cache. Instance data (`vault/`, `wiki/`) is never touched.
+
+If the directory already contains `.meta/`, `init` refuses; use `owfa upgrade` (or `--force` deliberately).
+
+### 4.2 git channel — the five manual steps
+
+**Clone-as-instance** (the clone *is* your workspace):
+
+```bash
+git clone https://github.com/owfadev/owfa.git my-workspace
+cd my-workspace
+# own the history if you do not want the framework's:
+rm -rf .git && git init
+```
+
+**Embed into an existing vault**: clone the template somewhere else, then copy the two trees into the target root:
+
+```bash
+cp -R /path/to/owfa/.meta          /path/to/my-workspace/
+cp -R /path/to/owfa/.agents/skills /path/to/my-workspace/.agents/
+```
+
+Then, at the workspace root:
+
+1. **Write `AGENTS.md`** — one identity paragraph, one layout paragraph, and the injection markers verbatim from [agents-example.md](agents-example.md). If an `AGENTS.md` already exists, paste in only the marker block (or let `owfa init` append it).
+2. **Create the four directories**: `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`. Derived pages build themselves.
+3. **Converge**:
+
+```bash
+python .meta/scripts/wiki_plugin_kernel.py all
+```
+
+Expected: all core plugins validate, package rosters reconcile, the injection region is rebuilt, command copies are in sync.
+
+### 4.3 "Installing the kernel"
+
+There is nothing separate to install. The kernel is the file `.meta/scripts/wiki_plugin_kernel.py` inside Core; Python 3.9+ runs it. Verify it:
+
+```bash
+python3 .meta/scripts/wiki_plugin_kernel.py validate   # structural check, read-only
+python3 .meta/scripts/wiki_plugin_kernel.py ls         # 21 core plugins
+python3 .meta/scripts/wiki_plugin_kernel.py pkg        # installed packages + core remainder
+```
+
+On Windows, `python` may be `py -3`; the CLI probes `python3`, `python`, then `py -3`. Set `OWFA_PYTHON=/path/to/python3` to override. If the kernel is missing, the Core copy is incomplete — recopy the tree, do not "pip install" anything.
+
+## 5. First run
+
+```bash
+cd my-workspace
+git init && git add -A && git commit -m "init: OWFA workspace"   # recommended
+```
+
+1. Put any file into `vault/` — `memo.txt`, a PDF, an image.
+2. Open an agent session at the workspace root and say **map**.
+3. The agent writes `wiki/vault/memo.txt.md` (SHA-256 + metadata), then the pipeline builds `wiki/index.md`, directory indexes, `tags.md`, `hot.md`, `log.md`.
+4. Say **check** — a green audit means the deployment is sound.
+
+The injection region in `AGENTS.md` now contains one block per full-tier plugin; the agent reads it as the structural contract. Everything outside the markers is yours.
+
+## 6. How to use it
+
+Open the agent at the workspace root; it reads `AGENTS.md` and `.agents/skills/`. Daily commands are natural language:
+
+| You say | What happens |
+|---|---|
+| map | register a vault asset as a wiki proxy page (hash, metadata, links) |
+| save | distill the current conversation into a native note |
+| query | answer from hot cache → index → grep, with wikilink citations |
+| check | repository health audit (structure + semantic checks) |
+| plugin | install / uninstall / list structural plugins |
+| profile | maintain the user cognition profile |
+| teach / quiz / cognition profile | course-learning family (needs a course domain, e.g. cuhksz) |
+| kernel reference | kernel usage and mechanics |
+
+The daily loops — library keeping, course learning, collaborative development — are in [usage.md](usage.md). Mechanics are in [mechanics.md](mechanics.md); the kernel reference skill is authoritative for flags.
+
+## 7. Packages — finding and installing
+
+Core ships only the framework plugins. External systems arrive as **packages**: one directory `.meta/plugins/domains/<pkg>/` with a `PKG.yaml` roster, plugin masters, commands and connectors.
+
+### 7.1 Find what exists
+
+Run these inside the instance:
+
+```bash
+owfa list                    # registry catalog: versions, compat floors, installed marks
+owfa pkg                     # what is installed here: members, connectors, core remainder
+# the same through the kernel:
+python3 .meta/scripts/wiki_plugin_kernel.py list-remote
+python3 .meta/scripts/wiki_plugin_kernel.py pkg
+```
+
+The registry is the GitHub index at `owfadev/registry`; before installing, it is also readable directly as `INDEX.yaml` in that repository. Each row shows the package version, the framework compat floor, the member plugins and the trust level.
+
+### 7.2 Install a package
+
+```bash
+owfa add cuhksz              # wraps kernel install + convergence
+# equivalent, and more explicit:
+python3 .meta/scripts/wiki_plugin_kernel.py install cuhksz --yes
+```
+
+This is also what the agent's **plugin** command does: you can ask the agent to install a package by name, and it drives the same kernel. The CLI is the human/script equivalent.
+
+What lands: plugin masters under `.meta/plugins/domains/<pkg>/`, command masters, in-repo connectors, skill copies, injection blocks, registry rows. Then the kernel converges. If the package declares a **first-run semantic migration** (root packages such as `project` do), the install stages it and `validate` stays red until an agent performs the semantic step:
+
+```bash
+python3 .meta/scripts/wiki_plugin_kernel.py migrate <pkg>
+# read the printed page, create the declaration/identity page, then:
+python3 .meta/scripts/wiki_plugin_kernel.py migrate <pkg> --clear
+```
+
+The CLI stops and reports this instead of pretending convergence. `owfa add` exits non-zero in that state.
+
+Other forms:
+
+- `kernel install <pkg>@<tag>` — pin a release tag;
+- `kernel install <owner>/<repo> --yes` — an unindexed repository (trust: unknown; `--yes` is the trust gate);
+- `kernel install <pkg> --path ./local-pkg` — a local package (channel C, no registry);
+- `--without a,b` — subset grammar is reserved; v1 reports not-yet-open. Offline alternative: copy `domains/<pkg>/` into `.meta/plugins/domains/` and rerun `all`.
+
+Trust levels are visible in `owfa list`: `framework-bundled` and `reviewed-3rd-party` install without a prompt; anything else needs `--yes` and is reported as unknown.
+
+### 7.3 Upgrade and uninstall packages
+
+```bash
+python3 .meta/scripts/wiki_plugin_kernel.py upgrade            # reconciliation report (read-only)
+python3 .meta/scripts/wiki_plugin_kernel.py upgrade <pkg> --yes # silent reinstall, per package, never cascaded
+python3 .meta/scripts/wiki_plugin_kernel.py uninstall <pkg> --yes
+```
+
+- Package versions are release ordinals riding their own tags; member plugin versions do not lockstep.
+- Upgrade stages semantic migrations when a version lands; clear them before the next mechanical action.
+- Uninstall does the mechanical four-clear (masters, commands, connectors, skills) plus a residual scan; **data zones and credentials are never auto-deleted**. A declared teardown stages a semantic-deletion warning and a residual gate. See [packages.md](packages.md).
+
+## 8. Upgrade the framework
+
+### npm channel
+
+```bash
+npx owfa upgrade            # replace .meta/ + .agents/skills/ with the channel's version
+npx owfa upgrade --check    # read-only report
+npx owfa upgrade --backup   # keep a copy under .owfa/backup/<version>-<timestamp>/
+```
+
+`upgrade` preserves the instance-local kernel state (`.meta/migrations/pending.json`, `.meta/kernel-journal.log`, `.meta/registry-cache.yaml`), replaces local edits under the two framework trees (instance hotfixes belong in git), and reruns `all`. A pending semantic migration blocks convergence and is reported with the exact `migrate` command.
+
+### git channel
+
+Re-copy `.meta/` and `.agents/skills/` from the new template revision (review the diff, do not blind-copy over pending migrations), then `kernel all`. The instance git snapshot is the rollback path.
+
+Framework versions are anchored by `.meta/VERSION` (0.3); a target-side semantic migration can be staged by an upgrade, with the same tri-face warning and `kernel migrate` flow.
+
+## 9. Uninstall
+
+- **A package**: `kernel uninstall <pkg> --yes`; data zones stay, credentials are only reminded, never deleted.
+- **The whole framework**: delete `.meta/`, `.agents/skills/`, and the `AGENTS.md` injection region block. `vault/` and `wiki/` are yours; dispose of them as you see fit. Nothing else is installed.
+
+## 10. Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `Python 3.9+ not found` | install Python 3, or set `OWFA_PYTHON`; the installer is Node-only, the runtime is Python |
+| `already contains .meta/` | it is an instance — `owfa upgrade`; `--force` re-copies the trees |
+| `npx` runs an old version | `npx owfa@latest …`; npm caches by version range |
+| `publish` / `npx` 403 on `owfa` | the name is frozen on similarity grounds; use the `owfadev` fallback or wait for the application |
+| upgrade blocked by pending migrations | run `kernel migrate <pkg>`, perform the semantic step, then `--clear` |
+| AGENTS markers missing | the AGENTS shell lost the `wiki-inject:start/end` pair; restore both, then `kernel all` |
+| Windows: `python` opens the Store | install Python 3 and ensure `py -3` or `python3` works; `OWFA_PYTHON` overrides |
+| kernel `list-remote` fails | network/raw access; the registry index is fetched from GitHub raw. The framework itself still works offline |
+
+## 11. File map after install
+
+| Path | Purpose | Safe to edit by hand? |
+|---|---|---|
+| `AGENTS.md` | identity/layout (yours) + injection region (kernel) | outside the markers, yes |
+| `vault/` | real assets | yes — the human owns it |
+| `wiki/` | markdown world, proxies, notes, sessions | yes, via commands; derived pages are rebuilt |
+| `wiki/index.md`, `tags.md`, `hot.md`, `log.md` | derived layer | no — the pipeline rewrites them |
+| `.meta/plugins/` | Core plugins + installed packages | no — framework authoring |
+| `.meta/scripts/` | kernel, pipeline, wikilib | no — framework authoring |
+| `.meta/command/` | command masters | no |
+| `.agents/skills/` | deployed skill copies | no — `kernel deploy` syncs them |
+| `.meta/migrations/` | staged semantic migrations + ledger | no — kernel zone |
+| `projects/` | project containers (if the project package is installed) | yes — project-owned |
+
+## 12. FAQ
+
+- **Existing vault with content?** Additive: `init` creates/extends the framework trees, never touches your files. New assets go through `map`; whether to proxy old content is your decision, incrementally.
+- **Can I use Obsidian?** Yes — it is a viewer. The framework writes plain markdown plus files; no plugin is required.
+- **Can I copy the whole `.agents/` tree?** Yes; this repository's `.agents/` contains only `skills/`.
+- **Windows?** Pure stdlib, no hardcoded paths; the CLI probes `py -3`. Git Bash or PowerShell both work.
+- **Offline?** `npm pack` the CLI on a connected machine, copy the `.tgz`, `npm install -g ./owfa-x.y.z.tgz`, then `owfa init`. Packages can be copied as `domains/<pkg>/` and converged with `all`.
+- **Multiple workspaces?** One instance per directory; they are independent. The CLI can init/upgrade any path.
+- **Where do plugins come from?** The registry index; unindexed repos are installable with `--yes` (trust: unknown). See [packages.md](packages.md) for the package model and `PKG.yaml`.
+
+## Appendix — command cheatsheet
+
+| Goal | Command |
+|---|---|
+| Install (target name) | `npx owfa init <dir>` |
+| Install (fallback name) | `npx owfadev init <dir>` |
+| Health check | `npx owfa doctor <dir>` |
+| Framework upgrade | `npx owfa upgrade <dir>` (or `--check` / `--backup`) |
+| Package catalog | `owfa list` / `kernel list-remote` |
+| Installed packages | `owfa pkg` / `kernel pkg` |
+| Install a package | `owfa add <pkg>` / `kernel install <pkg> --yes` |
+| Package upgrade | `kernel upgrade` (report) / `kernel upgrade <pkg> --yes` |
+| Package uninstall | `kernel uninstall <pkg> --yes` |
+| Pending migrations | `kernel migrate` / `kernel migrate <pkg> --clear` |
+| Structural check | `kernel validate` |
+| Full convergence | `kernel all` |

package/.meta/docs/developer.md

@@ -0,0 +1,33 @@
+# Developer guide: writing plugins & packages
+
+> Where a plugin lives is decided by its `depends`, not by taste — and the dev loop is the same wherever it lives: clone → branch → hack → `--path` install into a sandbox → PR.
+
+## Where does my plugin land?
+
+| Your plugin is… | It lands… | Trust gate |
+|---|---|---|
+| a **domain member** (depends chain reaches a domain root, e.g. bb-family) | that domain package's repo — PR there. Not a choice: the family closure claims it mechanically (`PKG.members` must include you or validate errors) | package maintainers |
+| a **new domain** of its own | your own repo as a package (`PKG.yaml`, see [packages.md](packages.md)) + a one-line PR to the [registry](https://github.com/owfadev/registry) | the registry PR — the human-review gate (inject text and connectors are the security faces, #12) |
+| **cross-cutting / non-domain** (global piece) | the framework repo's `core/` — PR there | owner review (charter-level, highest bar) |
+
+A single plugin never ships bare — the package is the distribution unit. A lone plugin is a single-member package (12 lines of PKG.yaml, see email/bili/project). Users prune with `--without` (subset grammar), so contributing into a big package never forces users to install all of it.
+
+## The dev loop
+
+1. **Clone the target repo** (package repo for domain work, framework for core) and branch: `module/topic`
+2. **Hack** — manifest (PLUGIN.yaml) + PLUGIN.md + skills per the existing patterns; versions advance along the changelog
+3. **Integration-test without a monorepo**: in the sandbox (or any instance),
+   ```
+   cd test-repo
+   python .meta/scripts/wiki_plugin_kernel.py install <pkg> --path /path/to/your/clone
+   python .meta/scripts/wiki_plugin_kernel.py validate --scope <pkg>
+   ```
+   `--path` installs the local clone (channel C); iterate freely — reinstall after uninstalling, or just re-copy
+4. **PR** — one thing per commit, `模块: 概述`; self-check per [CONTRIBUTING](../../CONTRIBUTING.md) (framework root: `validate`; sandbox: `all`)
+5. **Release** (package repos): bump PKG.yaml `version`, tag `<pkg>-v<X.Y>`, then bump the registry line — two small PRs, on purpose: the registry never freezes with the framework
+
+## Discovery: how people (and agents) find your work
+
+- **Before registration**: your repo is already installable (`kernel install <owner>/<repo> --yes`, trust: unknown) and findable via GitHub topics — tag the repo `owfa-package`
+- **After the registry PR**: listed in `kernel list-remote` (the agent surface), installable without `--yes`, trust: reviewed-3rd-party
+- **Write the summary for agents** — the registry `summary` line and your SKILL.md `description` fields are what agents actually match against; a vague summary is undiscoverable

package/.meta/docs/distribution.md

@@ -0,0 +1,132 @@
+# Distribution
+
+> How the framework itself reaches a machine, and how it is upgraded. Packages have had a channel (registry + `kernel install`) since v0.3; the framework body had none — install was *clone, copy two trees, hand-write AGENTS.md*. This page records the npm channel that closes that gap.
+
+## Why npm
+
+The framework is pure-stdlib Python with no runtime dependencies. npm is not a runtime choice here; it is a **delivery vehicle** chosen because it already exists on the machines that run agents:
+
+- one command, no clone: `npx owfa init my-workspace` (target) / `npx owfadev init` (fallback while the npm name is under application)
+- a versioned, immutable, checksummed artifact (the npm tarball) instead of a moving branch
+- Windows does not need Python's script directory on `PATH` (the failure that motivated #46)
+- `npx` keeps a cache, so re-running is cheap; upgrades fetch a new tarball by version
+- no `postinstall` scripts: `npm install` executes nothing from this package
+
+Python remains the only runtime dependency of the framework. Node is needed to *install*, not to *use*.
+
+The name is part of the channel: **OWFA — One Workspace For All (agents)**, with **OWFA Core** as the framework body and **OWFA CLI** as this installer. The target package is `owfa`; the name is **frozen** under npm's similarity policy (too close to `ow` / `ora`), so publication waits on an application and the fallback package is `owfadev` (same code, bins `owfa` + `owfadev`). The GitHub home target is `owfadev/owfa`. See [naming.md](naming.md) for the layers and the collision policy.
+
+## What ships
+
+The npm tarball is the framework body, byte-for-byte what the git channel copies:
+
+| Path | Contents | In tarball |
+|---|---|---|
+| `.meta/` | kernel, plugins, commands, protocol, docs | yes |
+| `.agents/skills/` | command/connector skill copies | yes |
+| `templates/AGENTS.template.md` | the instance shell with the injection markers | yes |
+| `bin/owfa.js` | CLI (zero dependencies) | yes |
+| `README.md`, `LICENSE` | — | yes |
+| `test/`, `scripts/`, `CONTRIBUTING.md`, `.github/` | development-only | no |
+
+Local state never ships: `__pycache__`, `*.pyc`, `.meta/kernel-journal.log`, `.meta/migrations/pending.json`, `.meta/registry-cache.yaml`, `test-repo/`. The release gate (`scripts/verify-release.js`) refuses to publish if any of them would be packed.
+
+## Commands
+
+```
+owfa init [dir] [--name NAME] [--packages a,b] [--force]
+owfa upgrade [dir] [--check] [--backup] [--force]
+owfa doctor [dir]
+owfa add <pkg> [--yes] [--without a,b]
+owfa list
+owfa pkg
+owfa version
+```
+
+**init** — additive deployment, the five manual steps in [deployment.md](deployment.md) mechanized:
+
+1. copies `.meta/` and `.agents/skills/` from the tarball
+2. creates `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`
+3. writes `AGENTS.md` from the template when absent; when one exists, **appends only the injection region** (handwritten content before it is preserved byte-for-byte); refuses if the markers are half-present
+4. runs `python .meta/scripts/wiki_plugin_kernel.py all` (validate, inject, registry, skills)
+5. optionally installs packages from the registry (`--packages cuhksz,lark`)
+
+A package may declare a **first-run semantic migration** (root packages such as `project` do). Installing it stages the migration, and the CLI stops there with the exact `kernel migrate` command — clearing it is an agent act (create the identity/declaration page), not something a mechanical installer may fake. `init --packages` therefore exits non-zero in that state: the workspace is installed but not converged.
+
+`--force` re-copies the framework trees over an existing instance, preserving the kernel state listed below. Instance data (`vault/`, `wiki/`) is never touched by any `init` or `upgrade`. If `.agents/skills/` already exists, framework skill copies with the same names are updated in place; unrelated skills are left alone.
+
+**upgrade** — tree replacement plus convergence:
+
+- compares the instance's `.meta/VERSION` with the tarball's; refuses downgrades unless `--force`
+- preserves instance-local kernel state: `.meta/migrations/pending.json`, `.meta/kernel-journal.log`, `.meta/registry-cache.yaml`
+- **replaces** local edits under `.meta/` and `.agents/skills/` — instance hotfixes belong in the instance's git history, which is the rollback path (the `--backup` flag also drops a copy under `.owfa/backup/<version>-<timestamp>/`)
+- reruns `all`; a pending semantic migration blocks convergence and is reported with the exact `kernel migrate` command
+- `--check` is a read-only report
+
+**doctor** — prints Node/Python/framework versions, checks the AGENTS injection markers, runs `kernel validate`. It never writes.
+
+**add** — thin wrapper over `kernel install` plus convergence. Registry trust rules still apply; `--yes` is forwarded. A staged first-run migration stops the command with the exact `migrate` hint (exit non-zero) instead of a false "done".
+
+**list** — `kernel list-remote`: the registry catalog with package versions, framework compat floors, member plugins, trust levels and installed marks. **pkg** — `kernel pkg`: what is installed in this instance (packages, members, connectors, core remainder).
+
+## Version invariant
+
+The npm version rides the framework anchor: `.meta/VERSION` `0.3` → package `0.3.x`. The release gate refuses a package whose `major.minor` diverges, and refuses a `v*` tag that does not match the package version exactly. `.meta/VERSION` still tracks the kernel contract, not product maturity (stage labels live in the README); npm patch releases may fix packaging without touching the contract.
+
+Install identification is therefore trivial: `.meta/VERSION` says which framework a workspace is on; `owfa version` says which channel the CLI is on.
+
+## Release runbook
+
+One-time:
+
+1. Settle the public home: create the `owfadev` GitHub org and move the repo to `owfadev/owfa` (a transfer, not a copy; GitHub redirects the old URL). Update `package.json` `repository`/`homepage` and the README links in the same commit.
+2. Apply to npm support for `owfa` (frozen on similarity grounds), with the org/repo, the docs and this channel as evidence. A 404 is not availability.
+3. Create the npm account/org that will publish; if the application is not granted, publish the fallback `owfadev` (bins `owfa` + `owfadev`) and keep `owfa` as the brand.
+4. Add `NPM_TOKEN` as a repository secret (automation token with publish rights), or run `npm login` locally for a manual first release.
+
+Every release:
+
+```bash
+# 1. the framework contract and the package version move together
+$EDITOR .meta/VERSION          # e.g. 0.3 -> 0.4
+$EDITOR package.json           # "version": "0.4.0"
+git commit -am "release: framework 0.4.0"
+git tag v0.4.0 && git push --follow-tags
+```
+
+The tag triggers `.github/workflows/publish.yml`, which re-runs the release gate, publishes with `--provenance`, and fails closed on any mismatch. For a manual release: `npm publish --access public --provenance`.
+
+Before tagging, run locally:
+
+```bash
+node scripts/verify-release.js
+node test/smoke.js
+npm pack --dry-run
+```
+
+## Security posture
+
+- **Zero dependencies** — nothing to audit but this package.
+- **No consumer lifecycle scripts** — `prepublishOnly` runs for the publisher only; installing or running `owfa` never executes package scripts.
+- **Provenance** — CI publishes with npm provenance, binding the tarball to this repository and commit.
+- **Additive by default** — `init` only appends to `AGENTS.md`; all destructive replacement is explicit (`upgrade`, `--force`) and reversible through instance git.
+- **No telemetry** — the CLI talks to npm only when npm itself does; `init`/`upgrade` do not phone home. Package installs from the registry are the kernel's existing GitHub-based channel, unchanged.
+
+## Scope and non-goals (v1)
+
+- Domain packages stay on the registry/`kernel install` channel. `owfa add` is a convenience wrapper, not a second package format.
+- No self-update of the CLI from inside the CLI; `npx owfa@latest` is the update path.
+- No platform installers (Homebrew, apt, pipx). The npm tarball is the single artifact; a PyPI mirror can be added later without changing the payload.
+- Offline install: `npm pack` on a connected machine, copy the `.tgz`, `npm install -g ./owfa-x.y.z.tgz`, then `owfa init`.
+- The git channel remains fully supported: clone-as-instance and developer template workflows are unchanged.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `Python 3.9+ not found` | install Python 3, or set `OWFA_PYTHON=/path/to/python3`; the installer itself is Node-only |
+| `already contains .meta/` | the directory is already an instance — use `owfa upgrade`; `--force` re-copies the trees |
+| `npx` runs an old version | `npx owfa@latest …`; npm caches by version range |
+| upgrade blocked by pending migrations | run `python .meta/scripts/wiki_plugin_kernel.py migrate <pkg>` and follow the printed page before upgrading again |
+| publish fails: name too similar | npm froze `owfa` (similar to `ow`/`ora`); use the `owfadev` fallback or wait for the application; do not retry the same name |
+| Windows: `python` opens the Store | install Python 3 and ensure `py -3` or `python3` works; `OWFA_PYTHON` overrides detection |

package/.meta/docs/intro.md

@@ -0,0 +1,56 @@
+# Introduction
+
+> Reader: team members, contributors, and anyone who wants to understand this design. For what the mechanics *are*, the authoritative sources are the kernel reference skill and the AGENTS.md injection region. This document explains *why* we arrived here: narrative and lineage, not a mirror of the mechanics. Written 2026-10-04.
+
+## 1. The starting problem
+
+In every session, the agent acquires information in SASU-L order: system prompt, AGENTS.md, Skills, the user's own words, loop. The system prompt carries no information about the vault; users assume the agent remembers last time, which is impossible. Cross-session information acquisition can only rely on the agent actively reading, and in real deployments the agent has zero prior knowledge of the vault. The pain of using an AI assistant is often not a lack of intelligence, but having to reintroduce yourself every time: where your assets are, what you are studying, where the last decision left off.
+
+## 2. The file foundation
+
+Markdown plus plain files is the foundation. No tool-private formats; Obsidian and WebUIs are merely replaceable viewers. Now the agent can read the vault—but "being able to read" is not "knowing what to read". Reading without signposts is blind: read everything and the context explodes; miss a read and information goes dark. What the framework solves is not storage, but the structure of information disclosure.
+
+## 3. The pointer mechanism
+
+Pointers are low-cost signposts resident in context: location and summary are always present, and the summary is the entire source of filtering efficiency; trigger conditions and post-trigger actions are paired as needed. Progressive disclosure has three layers: pointers stay resident at minimal context cost; the pointed-to targets are read on demand; referenced material is drilled into further. index drilling down level by level is exactly this structure.
+
+Two corollaries run through the whole framework:
+
+- **Never hand-write what can be derived**. Hand-written pointers rot—targets move, descriptions go stale; derived pointers are mechanically regenerated, immune to rot. This is the philosophical starting point of one source, five projections
+- **The ultimate purpose of disclosure is not "can be found", but "recalled when it should be recalled"**. todo is the explicit instance of a time-dimension pointer, pointing at what should be recalled at some future moment; injection lines carrying a "when to read first" condition are proactive pointers; consumes brings rules on-site when a command triggers—the same idea
+
+## 4. Pluginization
+
+The architecture does not enumerate. File formats and note types do not enter the constitution—types are frontmatter fields; structure is specified by each plugin on its own. One plugin, one directory: the manifest is the machine-readable essence; PLUGIN.md records the design rationale; attached-audit scripts are optional. A plugin holds a territory—which slice of paths belongs to whom, and what the write model is—and holds the outward-facing fields and disciplines.
+
+The domain is the core abstraction. wiki recognizes only inside versus outside; an external domain is an adapter contract, embodied in six questions: external territory, landing strategy, identity proof, wiki territory, write model, trust model. Landing is essentially a write-model choice: final-state assets go into append-only storage; process containers get full read-write authority; when the truth lives elsewhere, use pointers. Borrowing vault or pointers is the default posture; a self-standing container is the exception.
+
+## 5. Projections
+
+One set of manifests is mechanically projected to five places: the AGENTS injection region; the check inspection blocks; the command usage blocks, ordered by consumes; the registry field section; the deployed skill copies. All are idempotently rebuilt, automatically synchronized on (un)install, and presence is registration. There is no second source of truth: to change the contract, change the manifest, and one command converges everything. A deployed instance is self-sufficient carrying only the injection region and skills—mechanism documentation lives in the runtime-visible surface, and no separate set of architecture documents that would drift is written.
+
+## 6. Layering and bridges
+
+- **Material layer vs. archive layer**: process artifacts live in domain workspaces—fetched material, notes, graded quizzes all included; distilled conclusions live in the wiki. The wiki receives distillates, not process
+- **Global components vs. domain components**: cross-cutting services and their homes are global components—trust, log, todo, calendar, notes, user-profile—which may declare bridges; domain components belong to a domain transitively via depends. The bridge carries validation and declaration—required-bridge completeness, optional-bridge tolerance; disclosure distribution belongs to the projections
+- **Collection channels**: consumer-side plugins can take the thinnest form—zero territory, pure workflow, with usage routed via the source side and aggregated on-site at the hub command. Teaching and quizzing both close the loop around the cognition profile
+
+## 7. The team turn
+
+On 2026-10-02 the project switched from personal use to a team project. Collaboration red lines—data boundaries, git discipline, the commit process—see the "User requirements" section of AGENTS.md, whose authority always remains AGENTS.md itself. Development artifacts enter git; instance data never does. The framework is a universal product; real courses, grades, privacy, and credentials belong to the deployment instance.
+
+## 8. Lineage and map
+
+A minimal chronology: 2026-08 the personal vault founded; 09-08 the prototype landed, plugins plus commands; 09-12 the validate-by-use ruling; 09-19 to 09-30 domainization and connectors; 10-02 the team turn and governance rules; 10-04 the cognition consumer side established and mechanism documentation opened. For the full stream see `log.md` and git history.
+
+| Want to know | Go read |
+|---|---|
+| Constitution and collaboration red lines | `AGENTS.md` |
+| Mechanics overview | the kernel reference skill |
+| How the mechanics work | `.meta/docs/mechanics.md` |
+| Daily usage | `.meta/docs/usage.md` |
+| Using the sandbox | `.meta/docs/sandbox.md` |
+| Why a plugin is designed this way | that plugin's `PLUGIN.md` |
+| Research basis | `.meta/docs/research-*.md` |
+| Deployment guide | `.meta/docs/deployment.md` (five-minute path: `.meta/docs/quickstart.md`) |
+| Run history and current state | `log.md` |

package/.meta/docs/log-example.md

@@ -0,0 +1,19 @@
+# log.md — instance seed example
+
+> The run log of an instance (the framework repo itself keeps none — its change trail is git history + PRs + issues). Created by the log command on first write; the agent never rewrites old entries.
+
+```markdown
+# 运行日志
+
+> 置顶追加、只增不删；条目 = `- YYYY-MM-DD <类型> [<域>]：一句话`（域标可缺省——无域事务，log 桥）。规则见 `.meta/plugins/core/log/`，写走 `pipeline.py log`。
+
+- 2026-10-12 other：<one sentence: what happened, from which domain, with what outcome>
+- 2026-10-12 map：<one sentence per mapping transaction>
+- 2026-10-11 save：<one sentence per note landed, with the page name>
+```
+
+Shape rules:
+
+- **Prepend at the top, never rewrite** — the log is append-only history; window overflow is archived mechanically to `wiki/archive/<month>/log.md`, never trimmed by hand
+- **One transaction, one line** — type (`map/save/query/check/plugin/todo/profile/other`) + optional `[domain]` tag + one sentence; evidence and detail live on pages, the log records that they happened
+- Write through the pipeline (`pipeline.py log <type> <text>`), which enforces the window and the archive; hand edits are legitimate for humans but keep the format

package/.meta/docs/map.md

@@ -0,0 +1,23 @@
+# Docs map — what to read when
+
+> The routing table for `.meta/docs/` (framework) and package-repo docs. The entry index for agents; skills point here, the documents stay the source of truth.
+
+| Situation | Read |
+|---|---|
+| User reports dissatisfaction with agent behavior; behavior self-audit | [agent-behavior.md](agent-behavior.md) — feedback handling (consent gate) → routing → the seven-step standard |
+| Filing feedback — which repo owns it | [agent-behavior.md](agent-behavior.md) §Routing |
+| How packages / install / upgrade / migrations work (design + decision ledger) | [packages.md](packages.md) |
+| Deploying an instance; components (CLI/Core/kernel); channels; packages; upgrades; troubleshooting | [deployment.md](deployment.md) |
+| Five-minute install path | [quickstart.md](quickstart.md) |
+| Installing/upgrading the framework body; npm channel; release runbook | [distribution.md](distribution.md) |
+| The name: OWFA expansion, two names two jobs, collision policy | [naming.md](naming.md) |
+| Converting a legacy (pre-split flat) instance to the package era | [conversion.md](conversion.md) — the eight-step drill walked on a real instance |
+| Instance git usage (snapshots, red lines, recovery) | the [instance-git plugin](../plugins/core/instance-git/PLUGIN.md) (core 21) |
+| Framework mechanics: projections, bridges, injection, inject tiers | [mechanics.md](mechanics.md) |
+| (Un)install history, package lifecycle | [mechanics.md](mechanics.md) §7 + [packages.md](packages.md) |
+| Experiments: sandbox or local | [sandbox.md](sandbox.md) |
+| Development rules, commit flow, template + instance workflow | [CONTRIBUTING.md](../../CONTRIBUTING.md) — template-repo root (an instance reads it there, never keeps a copy) |
+| Day-to-day usage loops | [usage.md](usage.md) |
+| What the framework is, intro | [intro.md](intro.md) |
+| Package-side plugin docs (bb family, lark family, …) | the owning `pkg-*` repo's plugin masters |
+| AGENTS.md seed / log seed examples | [agents-example.md](agents-example.md), [log-example.md](log-example.md) |