owfadev 0.0.1 → 0.3.0

package/.meta/command/save/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: save
+owner: [notes, sessions]
+consumes: [notes, sessions, trust, index, hot, log]
+description: "Save the current conversation, answers, or insights as wiki native notes. Deduplicate before filing, infer type and title, chunk-extract long sessions, update index/log/hot cache. Triggers on: save this, /save, file this, save to wiki, 保存."
+---
+
+# save: capture
+
+Good answers should not vanish in chat history. Save what was just discussed as permanent wiki pages. The wiki compounds through it — save often.
+
+## Scope
+
+Write: sessions (session backbone pages), notes (native notes), log, hot, index
+Read: registry (`.meta/protocol/registry.yaml`, field and value-set anchor), tag (vocabulary `wiki/tags.md`), trust (generated), index / hot (dedup prerequisites)
+
+## Dedup Before Filing (required)
+
+1. Read wiki/hot.md and wiki/index.md for recent context
+2. Search existing pages by title and key concepts
+3. A related page exists: never rewrite directly — show the differences and let the user adjudicate (append-style merging requires a user instruction and leaves traces, or the human edits by hand, or a new page is created); partial overlap: likewise, show the differences and let the user choose
+4. Create a new page only after confirming none covers it
+
+## Type and Destination
+
+type / status value sets defer to the registry (a one-time read anchor; do not re-copy the table); ask only on genuine ambiguity. Destination splits by type: session goes to the long-sessions section below, other native types land in `wiki/notes/` (per-type destinations and contracts in the injection region); the source type is out of scope here — anything with a vault counterpart goes through map.
+
+## Workflow
+
+1. **Anchor (one-time read)**: read `.meta/protocol/registry.yaml` and `wiki/tags.md` — type / status value sets and the existing vocabulary are visible before writing
+2. Scan the conversation for high-value content (non-obvious insights, decisions with reasons, hard-won analyses, comparisons that will be cited again); skip mechanical Q&A / debugging processes / content already in the repository
+3. Set the type (ask only on genuine ambiguity) and title (ask only on ambiguity or conflict)
+4. Rewrite in declarative present tense: write knowledge, not dialogue
+5. Create the page per the write-side contracts in the injection region (notes / sessions destinations and shapes, trust generated, tag labeling); the session type goes to the long-sessions section
+6. Write wiki pages mentioned in the conversation into related with wikilinks
+7. **Post-write pipeline** (deterministic, mechanical, automatic): execute each plugin's write calls in injection-region order, then finish with `python .meta/scripts/pipeline.py verify` (post-write self-verification; on failure, go back and fix); then commit per the commit discipline (`保存: <page title>`, see `.meta/protocol/actions.md`)
+8. Report: `Saved as [[title]] in wiki/notes/` (session type: `... in wiki/sessions/`)
+
+## Long Sessions (session backbone)
+
+1. Split into 3-8 sections by topic (not by message count); merge and drop mechanical details
+2. Create the session backbone page: destination, default naming, participants, backbone-page shape, and promotion rules in the sessions block of the injection region
+3. Ask about the title only on genuine ambiguity
+
+## Writing Rules
+
+Declarative present tense; output language takes the default key of the language declaration page `wiki/language.md` (a missing page or missing key falls back to the session language); every concept / page mentioned gets a wikilink; a future session must be able to cold-read this page.
+
+## Parameters
+
+- `/save` saves the whole session; `/save <topic>` saves only that topic; `--force` skips confirmation (only when conflict-free)
+
+## Injected Section (plugin usage blocks)
+
+> This region is a wiki_plugin_kernel projection: consumes pulls merged with usage_routes source-side routing; disclosure order = owner first, routed blocks in the middle, pulled blocks last (rebuilt by inject / all); handwritten content does not belong here — to change the write-side contract, edit PLUGIN.yaml.
+
+<!-- cmd-inject:start -->
+<!-- usage:notes -->
+- Landing spot `wiki/notes/<title>.md`, file name free (named by humans); type form vocabulary in registry (open, self-extended by instances), territory values do not land in this zone
+- Append-only: commands never rewrite an existing note wholesale; updating = append-style merge under user instruction (trace left in the body) or manual human edits
+<!-- /usage:notes -->
+
+<!-- usage:sessions -->
+- Landing spot `wiki/sessions/YYYY-MM-DD-<topic>.md` (default naming), type: session, participants required (actor list)
+- Backbone page five-section shape: Core Conclusions / Decisions & Rationale / Non-obvious Insights / Open Questions / Related Pages (full-shape sample in the Example section of `.meta/plugins/sessions/PLUGIN.md`)
+- Standalone high-value topics promoted to `wiki/notes/` pages, the backbone page keeping a wikilink; dedupe before promotion
+<!-- /usage:sessions -->
+
+<!-- usage:language -->
+- Register discipline: follow the language.register audience reading level when writing saved artifacts; absent register uses the program baseline (first/second-year undergraduates), while explicit user audience requirements and domain source-alignment rules take precedence
+- When to read: read the declaration page before writing any artifact (wiki pages, documents, lecture distillates); page or key absent = follow the session language (conversation language is the output language); proper nouns, code, paths, commands, and file names always keep their original form (language neutrality, invariant under configuration) — the framework presets no specific language; Chinese is merely an instance fact of this project's development period (AGENTS principle 7)
+- Term discipline: when writing hits a term, consult the `terms` mapping first — if tabled, follow the table; otherwise annotate the original in parentheses on first occurrence (e.g. '检索增强生成 (RAG)'), registering only after recurring hits (emergence-based); a registered entry = a single line original→translation, long notes (translation rationale, usage examples) go to the body distillation section
+- Layering: a default baseline, not a mandate — the domain plugins' source-alignment discipline (exam language follows samples/course materials) takes precedence over this page; tag word forms belong to tag, forms of address and personal dynamic preferences belong to user-profile, in-domain term tables (the bb courseware glossary) are self-managed within the domain — none of these are restated on this page
+- Maintenance: the `language` mapping is human-defined first, the agent may propose; the `terms` mapping may be registered by the agent but never overwrites human-defined entries (objections reported); the body distillation section is append-only
+<!-- /usage:language -->
+
+<!-- usage:trust -->
+- When writing a page, write `generated` along the way (block style: `by: agent/<current-model>` / `at: <today>`)
+- When a review action happens, append a `verified` event (single line `by: <actor>, at: <date>`), never fabricated to inflate the level
+- Reviews are initiated by the user (triggered by human instruction); agents never append verified events on their own
+<!-- /usage:trust -->
+
+<!-- usage:index -->
+- Post-write rebuild (mechanical, automatic): `python .meta/scripts/pipeline.py index` (index — overflow-offloading scheme, including deletion of obsolete old indexes after merge-back) and the same script's `tags` (tag reverse index); LLMs never hand-write indexes
+<!-- /usage:index -->
+
+<!-- usage:hot -->
+- Writing entries (mechanical, automatic): `python .meta/scripts/pipeline.py hot <type> "<wikilink + one-sentence essence>"` (type value set same as log, see the log block of the AGENTS injection region); window eviction and truncation are performed by the script
+<!-- /usage:hot -->
+
+<!-- usage:log -->
+- Writing lines (mechanical, automatic): `python .meta/scripts/pipeline.py log <type> "<one sentence>" [--domain <domain>]` (type value set in the log block of the AGENTS injection region; domain tag = domain-plugin name such as bb/lark/vault, mandatory for in-domain transactions, omitted for framework and native transactions); rolling window and archiving are performed by the script
+<!-- /usage:log -->
+<!-- cmd-inject:end -->

package/.meta/command/wiki_plugin_kernel/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: wiki_plugin_kernel
+owner: framework
+description: "Kernel and mechanics reference: the projector's subcommands (7 convergence — ls/validate/audit/inject/registry/deploy/all — plus 8 package-lifecycle: plan/install/uninstall/list-remote/migrate/upgrade/pkg/residual) + a full account of the plugin mechanics — manifest / dependencies / the three projections / command binding / bridge rules / layering principles (a bb-domain worked example). Triggers on: 插件内核, wiki_plugin_kernel, kernel, 注入块更新, 投影重建, 插件机制, 更新注入."
+---
+
+# wiki_plugin_kernel: kernel and mechanics reference
+
+`python .meta/scripts/wiki_plugin_kernel.py <subcommand>` — the framework side's only projector: PLUGIN.yaml is the body; the AGENTS.md injection region, the check check blocks, the command usage blocks, the registry plugin section, and the command and connector skill copies are all its projections. Idempotent, runnable at any time; drift is fixed on the run. This skill also serves as the **mechanics master outline**: a deployed instance carrying only the AGENTS.md injection region + skill copies is self-sufficient; this file is the authoritative home of the mechanics on the deployment side.
+
+## Subcommands
+
+| Subcommand | Purpose | Disk writes |
+|---|---|---|
+| `ls` | plugin list + dependencies + driven commands | none |
+| `validate` | compliance checks: manifest fields, acyclic dependencies, owner×commands bidirectional consistency, consumes present with usage, usage_routes targets present and not duplicating consumes, bridge rules; exit code 1 on error | none |
+| `audit` | attached audit: executes each plugin's `scripts/check.py` on discovery, read-only report (may take a plugin id to check just one) | none |
+| `inject` | rebuilds the three projections: the AGENTS injection region + the check check blocks + the command usage blocks | AGENTS.md, command SKILL.md files containing injection regions |
+| `registry` | rebuilds the registry.yaml plugin section (from each manifest's `fields`) | registry.yaml |
+| `deploy` | syncs skill masters (`.meta/command/*/` commands + `connectors/*/` connectors) → `.agents/skills/` copies; orphan copies are reported only (deletion belongs to the human) | copies |
+| `all` | validate + inject + registry + deploy in one step | all of the above |
+
+Package lifecycle (full wizard protocol and judgment rules: `.meta/command/plugin/SKILL.md`):
+
+| Subcommand | Purpose | Disk writes |
+|---|---|---|
+| `plan <pkg>` | dependency plan for a package about to land | none |
+| `install <pkg> [--yes] [--without ...]` | fetch from registry or path → `domains/<pkg>/`; owner/repo specs need `--yes` (unknown trust); stages pending migrations | package dir, projections, migrations staging |
+| `uninstall <pkg> [--yes]` | remove package + projections; stages teardown (x->0) when declared | inverse of install |
+| `list-remote` | registry catalog (INDEX.yaml): packages, versions, compat floors | none |
+| `migrate [<pkg>] [--clear] [--force]` | pending semantic migrations: status / clear (verify- and residual-gated, use-and-delete) | migrations staging |
+| `upgrade [<pkg>]` | compare versions against the registry; apply via silent reinstall | as install |
+| `pkg` | installed packages: members, versions, connectors | none |
+| `residual <pkg>` | anchor-surface reference scan (the default teardown gate) | none |
+
+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.
+
+## Typical scenarios
+
+- **PLUGIN.yaml changed** (inject / checks / usage / fields / version): `python .meta/scripts/wiki_plugin_kernel.py all` — the daily standard action; one command converges everything; if validate fails it blocks — fix and rerun
+- **Only refreshing injection blocks**: `inject` suffices, but note it modifies the `.meta/command/` masters; copies sync only via `deploy` — hence always use `all` in daily work
+- **Quick health check**: `validate` (structure) + `audit` (attached audit); a full audit (including semantic items) goes through the check command
+- **(Un)installing plugins**: the semantic flow (decisions, directory archiving, log line) goes through the plugin command; the mechanical steps inside it are exactly this CLI's `validate` / `all` / `audit`
+- **Connector skill changed** (`connectors/*/SKILL.md` master): run `deploy` (or `all`) to sync copies — connector skills never enter `.meta/command/` (the command family is pure wiki operation)
+
+## Plugin shape
+
+- **One plugin, one directory** (`.meta/plugins/<id>/`): `PLUGIN.yaml` (the manifest, the machine-readable body) + `PLUGIN.md` (pure documentation: design summary (why / family position / key rulings and rejected alternatives) / Structure / Invariants / Changelog — **design rationale and per-plugin details belong here**; mechanics commonalities belong to this reference) + optional `scripts/check.py` (attached audit)
+- **Manifest keys**: seven required keys `id / version / depends / updated / attachment / fields / inject`; optional `commands` (command names this plugin drives), `usage` (write-side contract list — the third projection source), `checks` (check-rule list — the check projection source), `bridge` (bridge declaration, see bridge rules), `inject_tier` (injection tier, see tier law below)
+- **attachment** = declares territory and borrow-read relationships (who owns which paths, who read-only consumes whose pages); **fields** = owned page fields (enter the registry, the global vocabulary); **inject** = the plugin's disclosure, one line (the full-disclosure home in the manifest either way; known to the agent the moment it enters the repository when tier is full, read on demand when tier is member)
+- **Attached-audit contract**: `scripts/check.py` defines `check(ctx)` returning `[{level, message}]`; read-only with zero side effects; fixes belong to commands/humans; an AST static check validates the contract's shape
+
+## Dependency mechanics
+
+- `depends` declares behavioral or semantic dependencies (e.g. a bridging piece depends on the concept plugins on both ends); validate checks existence and acyclicity (DFS)
+- **Domain plugins** = those whose depends chain reaches `domain`; those directly depending on domain are **domain bases** (vault / lark / project / email / bb). In-domain plugins belong to the domain transitively and need not connect to domain directly
+- **Injection order = dependency topology (the depended-on injected first) + alphabetical within a batch** — consumer-side plugins are injected after the producers' disclosures are present (e.g. bb-track before bb-teach / bb-quiz); there is no layering concept
+- A domain must be discoverable within the wiki (declaration page or injection line); domain plugins create no root container — course/in-domain artifacts live in the domain territory (both sides `<term>/<course>/` isomorphic), with the general-purpose container (vault) or pointers as the default posture
+
+## Tier law (issue #12 layer discipline)
+
+- **`inject_tier: full | member`** (optional, default full): **full** projects into the AGENTS.md injection region; **member** exits it — exposure rides on the family root's roster line (every member named with id + one phrase), the skill catalog (trigger-surface awareness), and L-layer reads (the manifest `inject` field stays the full-disclosure home either way)
+- Validate requires a member to reach a **full-tier domain root** through depends (family membership, else it exits into invisibility)
+- The projected plugin blocks carry a **byte budget** (15 KiB, derived from the smallest mainstream whole-file AGENTS.md cap minus handwritten allowance): over-budget is a validate error — compress pointer lines or re-tier domain members; the A layer holds pointers and red lines only, never procedures or formats (content contract in `protocol/experiments.md`)
+
+## Command-plugin binding
+
+- **owner × commands bidirectional declaration**: the command SKILL.md frontmatter `owner: <plugin id>` (or `framework`, explicitly ownerless), the plugin manifest `commands: [command name]`; a one-sided declaration on either side is an error
+- **consumes (pull side)**: the command frontmatter `consumes: [plugin list]` — the destination declares which plugins' usage to pull; mandatory for owner-driven commands and must include all owners
+- **usage_routes (source-side routing)**: the plugin manifest `usage_routes: [command name list]` — additional commands the usage lands in; installing a plugin lands its projections without touching the destination command (the push side of "presence means registration"); validate checks that targets are present, that routed plugins carry usage, and that duplication with consumes is an error
+- **Disclosure order**: owner blocks first (consumes order), routed blocks in the middle (dependency topology plus alphabetical), the rest of consumes last — this is a presentation order, not an execution order
+- First case: bb-teach and bb-quiz each declare `usage_routes: [bb-track]` — the cognition hub automatically aggregates the collection channels' usage; the bb-track command's consumes keeps only its own and tools; `ls` prints the usage routing table (those without a landing point are marked as contract-document surfaces)
+- The **disclosure at the point of consumption** principle: the authoritative source of integration formats is usage (reaching commands via projection), not plugin prose — see the last item of the bridge rules
+
+## Projection mechanics (three projections, one source)
+
+- **The manifest is the only text source**; the kernel mechanically projects into three places, all idempotently rebuilt and auto-synced on (un)install:
+  1. **The AGENTS.md injection region** (`wiki-inject:start/end` marker blocks) ← the `inject` line — constitutional level, one block per full-tier plugin (member tier exits, see the tier law)
+  2. **The check check blocks** (`check-inject:start/end` inside the check command) ← the `checks` list — semantic-item check rules
+  3. **The command usage blocks** (`cmd-inject:start/end` inside each command) ← the `usage` list in consumes order — write-side contracts
+- A fourth mechanical projection: the **registry.yaml plugin section** ← `fields` (the global field vocabulary); a fifth: the **skill copies** (deploy)
+- Handwritten and mechanical regions are strictly separated: hand-editing inside marker blocks is forbidden (a rebuild overwrites); body text outside blocks belongs to humans; changing a contract = edit the manifest → converge with `all` — **there is no second source of truth**
+
+## Bridge rules (constitutional principle 11)
+
+- **Global plugins** (cross-cutting services and destinations: trust / log / todo / calendar / notes / user-profile…) may declare **bridges** — manifest `bridge: 必依|按需` (must-attach|on-demand); **domain plugins** may not hold bridges (any plugin whose depends chain reaches domain — holding one is an error)
+- **必依 (must-attach) bridges**: every domain base must carry the corresponding depends edge; a missing edge is an error (the topological-completeness invariant — e.g. the log must-attach bridge guarantees that anything a domain produces leaves a trace); **按需 (on-demand) bridges**: absence is tolerated (consumers skip without error, e.g. the user-profile cognition bridge)
+- **Division of labor between bridges and cmd-inject** (ruled 2026-10-04): bridges hold **validation and declaration** (who may attach, cardinality, completeness checks, absence tolerance); disclosure distribution belongs to projection (the authoritative source of integration-format details = usage, arriving at the point of consumption via cmd-inject, zero retrieval cost) — the bridge section (PLUGIN.md) recedes into elaboration and holds no format authority. The kernel of a bridge that cmd-inject cannot replace: the must-attach completeness check is a topological constraint that consumes cannot express; and cross-territory writes (todo/calendar/notes derivations) happen during every command execution, with no single-point command container to mount them in
+
+## Layering principles (in-domain example: the bb four-piece family)
+
+- **The material layer is in bb/ (the outer workspace), the archive layer in wiki/ (the inner territory)**: process artifacts (fetches, human notes, ai notes, exam grading) live in the material layer; settled conclusions (cognition readings, projection pages) live in the archive layer — "bb/ notes/: human-primary with ai cohabiting" and "user.md as a domain-native page" are instances of this layering
+- A domain's growth path: **the domain contract's six questions** (external territory / landing strategy / identity proof / wiki territory / write model / trust model) → the domain base establishes the territory (e.g. bb v0.7: both sides isomorphic + notes/ cohabitation) → the in-domain plugin family (bb-map projection rules, bb-track cognition profile) → consumer-side collection channels (bb-teach / bb-quiz: zero-territory workflow pieces whose usage mounts on the hub command via consumes) — **consumer-side plugins can take the thinnest form** (zero owned fields, contributing only usage and check rules)
+- A data-flow loop example: teach explains → ai notes land in notes/ (weak evidence) → track consumes and converges → quiz generates questions with reference → grading flows back into the evidence stream (machine evidence) — the three stages of material production, archive refinement, and collection write-back each belong to their own piece
+
+## Boundaries
+
+- The script touches only four sites: plugin directories in/out, injection-region marker blocks, the registry plugin section, and the skill deployment copies; the protocol / reserved sections and the AGENTS.md handwritten region are never touched
+- Pure standard library, zero dependencies (Python 3); English output
+- The data-zone derived layer (`wiki/index.md`, `tags.md`, `hot.md`, `log.md`) is not this CLI's business — that is `pipeline.py` (`index` / `tags` / `hot` / `log` / `verify`), invoked by the post-write pipelines of map / save
+
+## Parameters
+
+- Subcommand (see the table above); `audit` may take a plugin id

package/.meta/docs/agent-behavior.md

@@ -0,0 +1,68 @@
+# Agent behavior analysis & feedback protocol
+
+> L-layer home of the #34 ruling (C variant): the session is the full record, the issue carries the standardized artifact. Reader class: agents (via deployed copies) and developers. The analysis is generated by the agent itself, from its own loop context. Written 2026-10-13.
+
+## Feedback handling — the behavior face, now declared
+
+When the user reports dissatisfaction with agent behavior:
+
+1. **Immediate fix first** — stop the offending pattern in-session, never continue it while analyzing
+2. **Judge the responsible layer** — plugin constraint? framework? pure execution? Not a plugin/kernel matter → no analysis: respond to the user directly
+3. **Consent gate** — if it may be a plugin/kernel problem, offer the self-audit to the user (recommended, never forced); start only on consent
+4. **Systematic → behavior analysis** (below); one-off → in-session fix + one log line, no issue
+
+This face was previously undeclared (an e-class vacuum live sample, #33's improvised handling).
+
+## Routing — where feedback goes
+
+| Feedback | Destination | Test |
+|---|---|---|
+| kernel / mechanics / projections / core plugins / framework docs | owfa | framework contract face |
+| package member plugins (the bb family, the lark family, …) | the matching `pkg-*` repo | plugin id ∈ `PKG.members`; repo address in the registry INDEX |
+| behavior deviations (the #34 face) | wherever the plugin lives | behavior contracts live in PLUGIN.md |
+| new plugin proposals | owfa (incubation; moves with the package when it lands) | no owning repo yet |
+| unclear | file on owfa; maintainers transfer | fallback (#20 precedent) |
+
+## Triage gate — step 0, not passed means no analysis
+
+① Systematic (the same scene recurs)? ② Reproducible (survives a session change)? ③ Constraint-related (not pure execution)? All three — otherwise: fix in-session + one log line, do not generate an analysis.
+
+## The analysis standard — seven steps
+
+**1. Anchor the event.** Locate the deviation point. Quote verbatim: the user instruction (U layer) + the user's correction.
+
+**2. Reconstruct the behavior chain (fact layer).** From the U-layer instruction, list the actions that actually happened, each with four fields:
+- **Action**: what was read / written / called / generated
+- **Basis**: a re-read verbatim quote (injection line / AGENTS.md / skill body / PLUGIN.md / session context) — never from memory
+- **Owning plugin**: ownerless steps marked "framework / system layer"
+- **Trace**: tool-call records / file reads-writes / log entries
+
+Only steps with verifiable traces enter this layer; steps that cannot be confirmed move to step 5 (interpretation).
+
+**3. Expected behavior — two sources, recorded separately.**
+- **Declared expectation**: re-read the plugin's L layer (PLUGIN.md behavior contract owns/activates/offers/withholds, the injection line) — quote it, or write "undeclared"
+- **User expectation**: the correction verbatim, from step 1
+
+**4. Locate the deviation.** Actual vs expected, item by item. Against declared expectation = a compliance diff; against user expectation = a demand signal. List separately.
+
+**5. Attribution (interpretation layer).** Five classes, multiple allowed, each with a confidence (high/medium/low), a verbatim constraint quote, and the minimal fix if it holds:
+
+| Class | Meaning | Destination |
+|---|---|---|
+| a constraint defect | wrong / ambiguous / over-executed | fix the plugin |
+| b constraint conflict | two plugins give inconsistent instructions | fix the plugins (priority or wording) |
+| c not delivered | member-tier exit / skill not loaded | check tier and dependency chain |
+| d execution deviation | constraint present, not followed (model side) | not a plugin problem; record, change nothing |
+| e spec vacuum | no constraint covers the behavior | add a behavior contract |
+
+**6. Suggested change.** Minimal fix + blast radius (which other scenes depend on this constraint). The agent proposes; weighing and deciding belong to the developer.
+
+**7. Artifact.** Output the full analysis in the `.github/ISSUE_TEMPLATE/agent-behavior.md` format, confirm with the user, file it on the owning repo per the routing table above.
+
+## Red lines
+
+- Quotes must be re-read from the source; reproducing constraint text from memory is forbidden
+- The fact layer holds no speculation; all speculation goes to the interpretation layer with a confidence mark
+- Attribution classification is mandatory — a blanket "the plugin is buggy" is not accepted
+- The `agent-behavior` word root (kept distinct from the user-behavior plugin, per the #34 terminology ruling)
+- Artifacts land on GitHub issues, never in the instance wiki

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

@@ -0,0 +1,34 @@
+# AGENTS.md — instance seed example
+
+> The framework repo itself carries no AGENTS.md (library posture — dev rules live in README/CONTRIBUTING). This is the seed an instance drafts at deployment step ③ of the deployment guide. Keep it short: one identity paragraph, one layout paragraph, the injection region verbatim.
+
+```markdown
+# <vault name> — personal/instance library
+
+<One paragraph: what this instance is for, whose, what lives here. Written by the human,
+rewritten freely — the agent never edits outside the injection region.>
+
+## Layout
+
+<vault root>: `vault/` real assets · `wiki/` the md world
+· `.meta/` + `.agents/skills/` the framework body (packages under `.meta/plugins/domains/`).
+
+## Git
+
+Instance snapshots follow the instance-git plugin (core) — the agent commits at transaction close (`type: summary`); beyond that contract, git usage is the human's own.
+
+<!-- wiki-inject:start -->
+
+## wiki 注入区
+
+> 本区为插件注入的投影，装卸插件时同步增删对应标记块；手写内容不进此区。
+
+<!-- wiki-inject:end -->
+```
+
+Rules of thumb:
+
+- The **injection region markers** (`<!-- wiki-inject:start -->` … `<!-- wiki-inject:end -->`) are copied verbatim; everything inside is kernel-managed — hand-writing there is lost on the next `kernel all`
+- Everything **outside** the region is yours; the agent treats it as constitution-level context
+- After the mechanical run, the region fills with one `<!-- plugin:<id> v<x.y> -->` block per full-tier plugin — that is the structural contract surfaces to every future session
+- The injection region has a hard byte budget (kernel-checked): if a package's roster line overflows it, re-tier members rather than trimming the region by hand

package/.meta/docs/conversion.md

@@ -0,0 +1,24 @@
+# Converting a legacy instance (pre-split flat layout) to the package era
+
+> Walked end-to-end on a real instance (2026-10-13 conversion drill: 35 flat plugins → core 21 + 5 registry packages, 36 green, all inits cleared on real assets). Before you start: **commit a baseline** — the conversion is a snapshot boundary; if anything goes wrong, `git checkout` back.
+
+## Eight steps
+
+1. **Baseline commit** at the instance root — the rollback anchor
+2. **Survey**: `ls .meta/plugins` (a flat list = legacy), `ls .meta/command`, `ls .agents/skills` — note any *non-framework* skills you keep (the drill kept `dsh-token`)
+3. **Swap the framework trees**: delete `.meta/{plugins,command,scripts,protocol,docs}` and the framework entries of `.agents/skills/` (keep your own tool skills); copy in the template's `.meta/{plugins,command,scripts,protocol,docs,VERSION}` and `.agents/skills/*`. Data zones (`wiki/`, `vault/`, domain data directories), `connectors/`, `AGENTS.md`, `.gitignore` are never touched
+4. **Converge**: `kernel all` — core 21 green; the AGENTS injection region rebuilds wholesale (the old flat blocks are replaced)
+5. **Install packages**: `kernel list-remote`, then `kernel install <pkg> --yes` per package. Connectors already present are **kept existing** (running venvs survive; connector code updates arrive via uninstall+install of the owning package)
+6. **Clear the inits**: `kernel migrate <pkg>` prints each declaration; a real instance usually already satisfies the verify criteria (identity / profile / declaration pages exist on real assets) → `kernel migrate <pkg> --clear`
+7. **Derived layer**: `pipeline.py index` (idempotent rebuild); `hot.md` needs no rebuild — entries are managed per-write with window eviction
+8. **Close the transaction**: one commit (`plugin: converted to the package era …`) + a log line; `kernel upgrade` should now report framework and every package up to date
+
+## Findings from the drill (already baked into the mechanism)
+
+- **Injection budget**: a fully-loaded instance (core 21 + all five packages) projects ~15.7K — the original 15 KiB budget (a core-20-era figure) was raised to 16 KiB; the 16K harness floor stays the anchor
+- **Existing connectors kept on install** (conservative semantics) — credential dirs and venvs are never touched
+- The **tri-face pending warning** makes the mid-conversion state visible in every session; clearing inits on real assets typically passes verify in one shot
+
+## If something breaks
+
+The baseline commit is your exit: `git log` finds it, `git checkout` restores the framework trees. Data zones were never touched — the worst case is a framework redo, never data loss.