owfadev 0.0.1 → 0.3.1

package/.agents/skills/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/VERSION

@@ -0,0 +1 @@
+0.3.1

package/.meta/command/asset-read/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: asset-read
+owner: framework
+description: "Extract text from assets of any format by path (md read directly / pdf via PyMuPDF / docx and xlsx unpacked with the standard library); outputs are cached in wiki/tmp and marked with stale_after — the unified channel and caching convention for source-origin reads. Triggers on: asset-read, 读资产, 回源, 提取文本, 读课件原文, read asset."
+---
+
+# asset-read: source-origin asset reading
+
+Read the text of assets of any format by path — the unified channel for source-origin reads: vault assets, bb/ fetched artifacts, and relative paths outside the repository are all eligible. Reading augments registration rather than replacing it: the proxy page's one-line description covers the overview; only a deep question goes back to the source.
+
+## Scope
+
+Read: assets of any format (file system outside wiki, read-only)
+Write: `wiki/tmp/` extraction cache (the only landing spot)
+
+## Steps
+
+1. Locate the asset path and extension; md / txt / csv are read directly and done — no cache is written
+2. Check the cache: if `wiki/tmp/<asset name>.txt` is present and not past stale_after → read the cache directly, do not re-extract
+3. On a miss, extract:
+   - pdf: PyMuPDF (`import fitz`; if missing, install it per the host's Python package manager — e.g. pip on dev desktops, uv on PEP 668 hosts; instance-level environment declarations in AGENTS.md take precedence); for large files, extract by page range or keyword location — never feed the whole book into context
+   - docx / xlsx: pure standard-library zipfile + xml text-node extraction
+   - other binaries: no deep read; report honestly "text extraction not supported"
+4. Write the output to `wiki/tmp/<asset name>.txt`, with a three-line comment header: source path / extraction date / stale_after = extraction date + 7 days
+5. Report key points with provenance (page number or section name)
+
+## Prohibitions
+
+- Never modify asset originals (the read-only discipline holds in whatever domain they live)
+- No bulk full extraction — single items on demand; one-off views are not cached
+- Cache expiry is reported as a list by check, and disposal requires confirmation (an existing rule of the tmp plugin; this command does not clean up on its own)
+
+## Language
+
+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); asset originals keep their original language and form.
+
+## Parameters
+
+- Asset path (root-relative); optional page range or locating keyword

package/.meta/command/check/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: check
+owner: framework
+description: "Audit the repository's health: hard-structure checks on the foundation and plugins + semantic checks on plugins and pages. Triggers on: check, 健康检查, 检查插件, lint."
+---
+
+# check: repository health audit
+
+This is an audit, not a guardrail. It outputs a graded report: error = structural breakage requiring action; warning = a suggested to-do. Check rules come from two places: the foundation part of this file (protocol level) + the injection region below (a mechanical projection by wiki_plugin_kernel from each plugin manifest's checks list; presence means registration).
+
+## Purpose
+
+Run one health audit over the entire instance (foundation + plugins + wiki pages).
+
+## Scope
+
+Read: everything (.meta/, the AGENTS.md injection region, .agents/skills/, the wiki/, vault/ directory trees)
+Write: one line in wiki/log.md (type "check"); regenerable zones are rebuilt directly per the action discipline (scripts: injection region / registry / command copies; semantics: index / tags / hot eviction / log archiving / hash recomputation)
+
+## Steps
+
+1. **Foundation hard checks** (protocol level):
+   - **Static self-check script**: `python .meta/scripts/wiki_plugin_kernel.py validate` (directory completeness, manifest seven fields + optional commands, id consistency, dependency existence, acyclicity, command binding owner×commands bidirectional consistency) — any error means FAIL
+   - **Idempotent rebuild**: `python .meta/scripts/wiki_plugin_kernel.py all` (injection region / registry plugin section / command copies — mechanical and automatic; drift is fixed here, the script source is the rule list)
+   - `.meta/protocol/registry.yaml` is in place with the protocol / reserved sections intact (the script never touches these two sections; a missing section is an error)
+   - **Value-set violation**: scan the frontmatter of all wiki/ pages; a type / status value outside the registry value set → error
+   - Every `.meta/command/` SKILL.md has frontmatter (name / description / owner; optional consumes — an ordered list of plugins whose write-side contracts are consumed; referenced plugins must be present with a usage list; mandatory for owner-driven commands)
+2. **Plugin checks**: first run the attached audit `python .meta/scripts/wiki_plugin_kernel.py audit` (mechanical items: each plugin's scripts/check.py executed on audit discovery, read-only reporting; errors count toward FAIL); then execute the items marked "semantic" in the injection-region blocks below
+3. **Semantic checks**: read plugin and command files, looking for dangling references (a command referring to nonexistent structure), ghost fields (page fields with no owning plugin and not registry-reserved), and injection-region blocks inconsistent with the PLUGIN.md Checks section
+4. Summary output: PASS / WARN / FAIL counts + graded details + vault backlog count (informational)
+5. **Fixes are executed by grade per the action discipline** (`.meta/protocol/actions.md`): mechanical-automatic items are done directly — `pipeline.py index` / `tags` (index rebuild), `wiki_plugin_kernel.py all` (registry / injection region / copies), hash recomputation (raw_sha256 of changed frontmatter); hot / log overflows are converged by their own write-pipeline commands; mechanical-confirmation items present a list and ask once; semantic items are reported only; historical entries are never automatically changed
+6. Prepend one line to wiki/log.md (type "check", via `pipeline.py log check "<one line>"`); if anything changed (fixes / a log line), commit per the commit discipline (`检查: <conclusion>`, see `.meta/protocol/actions.md`)
+
+## Tools
+
+grep / file reading suffice; no second scan when one read is enough (call frugality).
+
+## Parameters
+
+- None: full-repository audit
+- Plugin id: check that plugin only
+
+## Injected Section (plugin check blocks)
+
+> This region is a wiki_plugin_kernel projection from each plugin manifest's checks list (rebuilt by `inject` / `all`; presence means registration); handwritten content does not belong here — to change check rules, edit PLUGIN.yaml.
+
+<!-- check-inject:start -->
+<!-- check:device -->
+- Mechanical (attached-audit script `scripts/check.py`, executed discovery-style by audit): device block mapping's warranty_until within ≤30 days of today → warning nearing expiry; already expired → warning expired; invalid date → warning
+<!-- /check:device -->
+
+<!-- check:hot -->
+- Window out of bounds (>25 entries / >5 days / >200 chars per entry) → run `pipeline.py hot <type> "<backfill>"` once, or wait for the next write to converge naturally then re-check
+- Contradiction with log (log has records while hot shows no trace) → warning
+<!-- /check:hot -->
+
+<!-- check:language -->
+- Mechanical (attached-audit script `scripts/check.py`, executed discovery-style by audit): type: language landing outside `wiki/language.md` → error; terms empty values → warning; declaration page absent → info (session-language fallback tolerated)
+<!-- /check:language -->
+
+<!-- check:link -->
+- Mechanical items (attached-audit script `scripts/check.py`, executed on audit discovery): broken link (target is neither a page full name nor any page's aliases) → warning; hand-written broken link in hot → warning (not counted as an inbound-link source); garbled link (target contains the U+FFFD replacement character, including related items) → error; alias ambiguity (two pages declaring the same aliases, resolution indeterminate) → error; orphan page (no inbound links and no related references, inbound sources counting concept pages only) → warning for notes knowledge pages, info for territory-value registration pages (registry territory values except session, having no inbound links yet being the registration norm); one-way related (A lists B while B does not list back) → info
+- Semantic items (check command): inbound-link density top list → info item (evidence for hub emergence, no alert)
+<!-- /check:link -->
+
+<!-- check:log -->
+- Mechanical items (attached-audit script `scripts/check.py`, executed on audit discovery): undated entries (starting with `- ` yet not matching the date format, main file and archive checked alike) → error
+- Semantic items (check command): historical entries modified (verifiable via git) → error; capacity over the limit → re-check after mechanical archiving
+<!-- /check:log -->
+
+<!-- check:notes -->
+- Traces of a note overwritten by a command → error
+- Near-duplicate notes (Jaccard > 0.7) → warning
+<!-- /check:notes -->
+
+<!-- check:sessions -->
+- Mechanical (covered by audit): session-type pages outside `wiki/sessions/` (or the reverse) → warning; participants missing or entries violating the actor convention → warning
+- Semantic: backbone page bloated past due promotion (should have been promoted but was not) → warning
+<!-- /check:sessions -->
+
+<!-- check:tag -->
+- Mechanical items (attached-audit script `scripts/check.py`, executed on audit discovery): >5 tags on one page → warning; tags restating type → warning; hierarchy over the limit (parent/child ≤2) or empty segment → warning
+- Semantic items (check command): near-duplicate tags → warning suggesting a merge; merging is a mechanically-confirmed item (list presented, executed after user confirmation)
+<!-- /check:tag -->
+
+<!-- check:tmp -->
+- Semantic (v0.1 manual, attached audit deferred): type: tmp landing outside wiki/tmp/ → error; stale_after already past → warning (cleanup prompt); tmp page count > 20 → info (backlog triage)
+<!-- /check:tmp -->
+
+<!-- check:trust -->
+- Mechanical items (attached-audit script `scripts/check.py`, executed on audit discovery): generated missing by/at or wrong actor format, verified event missing by/at or wrong format, stale_after not YYYY-MM-DD, sources not a list → warning
+- Mechanical items (info level): stale page list (past stale_after); trust-level counts (human-reviewed / machine-confirmed counts)
+- Semantic (check command): stale-page disposition triage (refresh the moment / re-verify / deprecate) — human decides
+<!-- /check:trust -->
+
+<!-- check:calendar -->
+- Semantic (v0.1 manual, attached audit deferred): month page file name not YYYY-MM or landing outside wiki/calendar/ → error; traces of rewriting a past month's page → error (git audit); declaration page missing the `calendar` block → info (the manual-only norm)
+<!-- /check:calendar -->
+
+<!-- check:cron -->
+- Mechanical: a type: cron page landing outside wiki/cron/ → error; task page missing the cron block or the minimal key set (trigger/action/form/status) → warning; malformed condition trigger (kind outside the open vocabulary or missing target) → warning; time form: last_run beyond the schedule period with active → warning (projection-lost signal)
+- Semantic (attached audit deferred): per-form drift between readable execution-side lists (scheduler / system tasks / conditional-executor watches, best-effort) and the declaration page set → warning; unreadable executor → info
+<!-- /check:cron -->
+
+<!-- check:index -->
+- Deviation between indexes and the actual page set (including merged-back indexes pending deletion) → fixed by running `pipeline.py index` to rebuild (idempotent; no diff means consistent); same for tags (`pipeline.py tags`)
+- Traces of hand editing → warning
+<!-- /check:index -->
+
+<!-- check:todo -->
+- Mechanical (info-level): the list of date-triggered, overdue and unsettled entries (the mechanical basis for new-session reminders); page absent (the no-delegation norm)
+- Mechanical: entry missing trigger condition or by/at → warning; type: todo landing outside `wiki/todo.md` → error
+- Semantic (check command): open entries > 50 → warning (bloat triage: do what should be done, distill what should be distilled via save, confirm with the user what should be dropped)
+<!-- /check:todo -->
+
+<!-- check:user-profile -->
+- Semantic (check command): profile assertion missing an evidence wikilink → warning
+- Mechanical: a type: profile page landing in `wiki/notes/` or `wiki/vault/` (wrong territory) → error
+- Mechanical (info-level): profile page absent (the untriggered norm; profile self-creates on first trigger)
+<!-- /check:user-profile -->
+
+<!-- check:mapping -->
+- Mechanical items (attached-audit script `scripts/check.py`, executed on audit discovery): mirror diff (file in vault without proxy → info backlog; proxy without counterpart → error, message carries the reference count — see the impact surface before deleting); missing registration fields (raw_file / raw_sha256) → error; dangling raw_file → error; raw_sha256 mismatch → warning; suspected full-text duplication (md asset body ≥80% of the original) → warning; description-less stub with updated older than 90 days → warning
+- Semantic items (check command): mismatch-disposition triage (description still applies → mechanical recalculation auto-repairs, writing a log line on completion (type map, one sentence with the asset name and 'original changed, description still applies'); suspected invalid → human decides remap or delete); diary-type full-text duplication exemption judgment; before disposing an orphan proxy, handle its references first (update references in sync or leave aliases to redirect)
+<!-- /check:mapping -->
+
+<!-- check:structure -->
+- Mechanical items (attached-audit script `scripts/check.py`, executed on audit discovery): declaration diff — vault top-level directory undeclared → warning, declaration key pointing to a nonexistent directory → warning; type: structure landing outside `wiki/structure.md` → error; declaration page absent → info (flat tolerance)
+<!-- /check:structure -->
+<!-- check-inject:end -->

package/.meta/command/docs/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: docs
+owner: framework
+description: "Docs thin-router: points to the documentation map and the behavior/feedback protocol — no norms live in this skill. Fire when the user reports dissatisfaction with agent behavior (possible plugin/kernel cause), asks where something is documented, or how to file feedback. Triggers on: docs, 查文档, 文档在哪, 框架问题, 行为自检, agent-behavior, 怎么提issue."
+---
+
+# docs: thin router to the documentation layer
+
+S-layer pointer only — the norms live in the documents (L layer). Re-read what you cite; never quote from memory.
+
+## 1. User dissatisfaction → triage first, consent before any self-audit
+
+When the user reports dissatisfaction with your behavior, do **not** launch an analysis on your own:
+
+- **Not a plugin/kernel matter** (pure conversation, execution slip)? Ignore the rest of this skill — respond to the user directly, fix in-session.
+- **Possibly a plugin or kernel problem?** First ask the user whether to run a behavior self-audit (**recommended** — it produces the evidence base for a real fix). Only on consent, follow the protocol: [`.meta/docs/agent-behavior.md`](../../docs/agent-behavior.md) — feedback handling → routing → the seven-step standard.
+
+## 2. "Where is X documented?" / "how does X work?"
+
+Read [`.meta/docs/map.md`](../../docs/map.md) — the routing table (what to read when), framework docs and package-repo docs both.
+
+## 3. Filing feedback / issues
+
+The routing table lives in [`.meta/docs/agent-behavior.md`](../../docs/agent-behavior.md) §Routing: framework → owfa; package members → the matching `pkg-*` repo; new-plugin proposals → incubation on owfa.

package/.meta/command/map/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: map
+owner: mapping
+consumes: [mapping, trust, tag, index, hot, log]
+description: "Map assets in vault/ into wiki proxy pages: SHA-256, mirror path, frontmatter, index/hot-cache/log linkage. Triggers on: map, 映射, process this source, add this to the wiki."
+---
+
+# map: mapping
+
+Map assets in `vault/` into `wiki/vault/` proxy pages — mapping and understanding are decoupled: a pure registration action (registration fields, body scale, and other write-side contracts are in the injection region). It targets only assets already in vault and does no vault-side processing (organizing and polishing belong to vault governance, discussed separately).
+
+## Scope
+
+Write: mapping (proxy pages), log, hot, index
+Read: registry (`.meta/protocol/registry.yaml`, field and value-set anchor), tag (vocabulary `wiki/tags.md`), trust (generated), vault (originals)
+
+## Steps
+
+1. **Anchor (one-time read)**: read `.meta/protocol/registry.yaml` and `wiki/tags.md` — value sets and the existing vocabulary are visible before writing
+2. Read the target asset in vault/
+3. Assemble the proxy-page draft per the write-side contracts in the injection region (mapping mirror and registration fields, trust generated, tag labeling); **present the mapping preview** (path / hash / description / tags) and wait for user confirmation
+4. After confirmation, write the proxy page
+5. **Post-write pipeline** (deterministic, mechanical and automatic, no prompting): 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 (`映射: <asset name>`, see the vocabulary in `.meta/protocol/actions.md`)
+6. Report: path / hash / description / tags
+
+## Prohibitions
+
+- Never modify any vault/ file (the command side is append-only toward vault); other hard rules (hash always computed, body never a full copy, etc.) defer to the mapping block of the injection region
+
+## Language
+
+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); proper nouns and paths keep their original form.
+
+## Parameters
+
+- Asset path (relative inside vault/); batching allowed
+
+## 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:mapping -->
+- Mirror locating: proxy path = `wiki/vault/<original-path>.md` (original name + .md, prevents name collisions); md assets also get proxies, no exceptions
+- Registration fields: `type: source` + `raw_file` (root-relative path) / `raw_sha256` (hexadecimal SHA-256, never skip the computation)
+- Body starts with a one-line description, never copying the full original text; summary / structure extraction are optional enhancements; diary-type assets are registration-first, summaries not enforced
+- URL-type assets: the proxy page carries `url` (vault field — source link, source preservation; required when placed via agent channels, optional for manual placement)
+<!-- /usage:mapping -->
+
+<!-- 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:tag -->
+- Before writing, read `wiki/tags.md` and prefer reusing existing terms
+- New-term conventions: primary language follows the language page's default key (absent → session language, preventing mixed Chinese-English fragmentation of the vocabulary); English lowercase kebab-case; hierarchy ≤2; ≤5 per page; restating type forbidden
+<!-- /usage:tag -->
+
+<!-- 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/plugin/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: plugin
+owner: framework
+description: "Package & plugin lifecycle management: plan (disclosure wizard), install (three channels + --without subsets), uninstall, list-remote, upgrade, pkg, residual. Mechanical steps all go through .meta/scripts/wiki_plugin_kernel.py; the agent runs the consent conversation and the one-shot commands. Triggers on: plugin, 插件, 装插件, 卸插件, 装包, install package, uninstall package."
+---
+
+# plugin: package lifecycle
+
+The framework's self-management command, package era (issue #20). Every mechanical step goes through the kernel script; the agent's job is **consent and choice** — never writing `.meta/` by hand.
+
+## Scope
+
+Write: only via the kernel script (package masters in/out, connectors/, command masters, injection region, registry, skill copies — six sites)
+Read: INDEX via the kernel, PKG.yaml, manifests
+
+## Discovery → download: the consent wizard (human path)
+
+When a user asks to install a package and has NOT already specified what to include:
+
+1. `python .meta/scripts/wiki_plugin_kernel.py plan <pkg>` — one-shot disclosure plan: trust line, package disclosure (network/privacy/credentials, package-authored), baseline (the family root, always installed), optional members with one-line summaries and what each selection pulls in, connectors
+2. Relay the plan **in the user's language** (render at the agent layer per wiki/language.md — canonical texts are English; the agent translates when relaying, never edits the source)
+3. Walk the steps: trust + disclosure → user acknowledges; optional members → user picks (each pick auto-pulls its dependency closure — show the resolved final set, users cannot compose an illegal subset); connectors → confirm (they ride the package)
+4. Execute: `python .meta/scripts/wiki_plugin_kernel.py install <pkg> --without <unwanted> [--yes]`
+5. Report the convergence output (validate/inject/registry/deploy) in one breath
+
+## One-shot path (agent / pre-authorized)
+
+If consent already exists (user named exactly what they want, or pre-authorized), skip the conversation:
+
+```
+python .meta/scripts/wiki_plugin_kernel.py plan <pkg> --json        # machine-readable plan (optional)
+python .meta/scripts/wiki_plugin_kernel.py install <pkg> [--without a,b] [--yes]
+```
+
+Kernel commands never prompt — every invocation completes in one shot.
+
+## Transaction close: git snapshot
+
+Every package transaction (install / uninstall / upgrade apply / migrate clear) ends with **one git commit at close** — after validate goes green, mechanical + semantic changes in the same snapshot. The kernel itself never touches git (the journal is its ledger); committing is the agent's closing move. Message format `plugin: <verb> <pkg> [v<version>]` per the [instance-git plugin](../../plugins/core/instance-git/PLUGIN.md). Not a git repo? Skip silently.
+
+## Command surface
+
+| Command | What it does |
+|---|---|
+| `plan <pkg> [--json] [--without a,b]` | disclosure plan (+ subset preview); clone discarded, nothing installed |
+| `install <pkg>[@tag]` | registry path: trust gate → clone → verify (id/compat/members ↔ index) → place masters/connectors/commands → converge |
+| `install <owner/repo> --yes` | unindexed direct install (trust: unknown — the registry PR is how a package earns reviewed trust) |
+| `install <pkg> --path <dir>` | local package (developer loop, channel C) |
+| `install ... --without a,b` | D5 subset: named leaves + their dependents pruned; root never prunable; result is dependency-closed by construction |
+| `uninstall <pkg> --yes` | D6 four-clear + convergence + residual scan + retains/credentials reminders; data zones and credentials never touched |
+| `list-remote` | registry index with members and trust marks |
+| `upgrade` | reconciliation report; upgrades run uninstall+install per package, never cascaded |
+| `upgrade <pkg> --yes` | mechanical reinstall + update report (member deltas + changelog excerpts) + migration chain staging |
+| `migrate <pkg>` / `--clear` | pending status + declaration printing / verify-gated clear (deletes staged files, unblesses validate) |
+| `pkg` / `ls` / `residual <pkg>` | local inventory / plugin list / anchor-surface reference scan |
+
+## Semantic migrations (update path)
+
+Mechanical sync is only half an update. When a new version carries `migrations/`:
+
+1. The kernel stages declarations into `.meta/migrations/<pkg>/` (kernel zone — never inside the package dir), registers the warning ledger, and raises the **tri-face warning**: every kernel invocation prints the pending banner · `validate` stays red (mechanical blessing withheld) · a kernel-managed block lands in the AGENTS injection region so every session sees it
+2. `kernel migrate <pkg>` prints the staged declarations (init or version-chain) — relay them in the user's language
+3. Perform the semantic transformation via the normal command surfaces (confirmation gates as always); **judgment split rule**: assertions that hold only during the transition belong in the author's verify script (dies with the migration); assertions that hold forever belong in `scripts/check.py` (same release)
+4. **Subset matching**: declarations and verifies address the **installed subset**, never the full roster — steps marked `(member: X)` run only when X is installed; verify scripts guard member-specific assertions with `ctx.installed` (the kernel passes it); the ledger records the staging-time subset
+5. `kernel migrate <pkg> --clear` runs the author verify (AST-gated: read-only, stdlib-adjacent, must define verify(ctx)) — clean clears the warning and **deletes the staged files (use-and-delete: they are useful precisely once; keeping them would blur into check's role)**
+6. The kernel journal (`.meta/kernel-journal.log`) records install/uninstall/upgrade/warn/clear with a rolling cap of 500 lines (oldest trimmed); it is git-tracked — mechanical facts only; semantic narrative stays in wiki/log
+
+## Boundaries
+
+- **Consent is the agent's duty**: no install without user acknowledgment of the disclosure (unless pre-authorized); `--yes` gates exist precisely so consent is explicit
+- **Trust is earned in the registry**: unindexed = installable but flagged unknown; the one-line registry PR is the review gate (inject text and connectors are the security faces)
+- The script touches only its six mechanical sites; data zones (`wiki/`, `vault/`, `cuhksz/`, `projects/`), credentials (`~/*-cli`), and the AGENTS.md handwritten region are never touched
+- Errors from the script always block; warnings are reported only
+- Uninstall leaves data in place (deprecated posture); physical deletion belongs to the human

package/.meta/command/profile/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: profile
+owner: user-profile
+consumes: [user-profile, trust, index, hot, log]
+description: "Maintain the user profile wiki/profile.md: recognize self-description and behavioral signals, update assertions convergently (new values replace old, changes leave traces in the body, evidence wikilinks); construction and consolidation go through a whole-page rewrite preview. Triggers on: profile, 更新画像, 画像更新, update profile."
+---
+
+# profile: profile update
+
+Write the continuing cognition about the user into a checkable page: assertions carry evidence, preferences expire, updates leave traces. The direction is "inner → user cognition" — orthogonal to map (outer → inner translation) and save (sessions landing on disk); convergent across sessions, not a transactional one-shot. Write-side contracts (signal criteria, layered placement, assertion format, convergence traces) are in the injection region.
+
+## Scope
+
+Write: user-profile (wiki/profile.md), log, hot, index
+Read: registry (`.meta/protocol/registry.yaml`, field and value-set anchor), trust (generated / stale_after), the current profile page (may be absent)
+
+## Steps
+
+1. **Anchor (one-time read)**: read `.meta/protocol/registry.yaml` and `wiki/profile.md` — a missing page = first creation (construction), no reliance on an initialization mechanism
+2. **Judge signals** (criteria in the injection region): if this session's and recent observations do not qualify, report and exit — never force a write
+3. Assemble the update: incremental assertions (new value replaces old + body trace) or construction / consolidation (whole-page rewrite) — construction and consolidation **present a profile preview** (assertions / evidence / layers) and wait for user confirmation
+4. Write the page (layered placement and stale_after renewal in the injection region)
+5. **Post-write pipeline** (deterministic, mechanical and automatic, no prompting): 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 (`画像: <one line>`, see the vocabulary in `.meta/protocol/actions.md`)
+6. Report: what was updated / the evidence chain / which layer it landed in
+
+## Prohibitions
+
+- Privacy red line: profile content is instance data, never entering the framework repository or test-repo
+- Diary-type assets contribute only meta-signals (presence, cadence); their content never enters the profile
+- Evidence pages (session pages / vault proxy pages / lark archive pages) are referenced read-only, never rewritten
+
+## Language
+
+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); proper nouns and paths keep their original form.
+
+## Parameters
+
+- No argument: judge recent signals and update; `<topic>`: process only that topic's assertions
+
+## 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:user-profile -->
+- Dual-track triggering: the user explicitly invokes profile; the agent calls it spontaneously in any session upon recognizing significant signals — signal distillation uniformly goes through this command, not parasitic on other command flows
+- Signal criteria: self-reported signals (preference expressions, corrections, background) and behavioral signals (subjects, fields, material habits); record only recurring subjects/fields, explicit preference expressions, corrections to output, and stable background facts (identity/tools/environment); one-off and instrumental content and uncertain observations are not recorded
+- Evidence domain: any page inside wiki works (session pages, vault proxy pages, lark archive pages, notes) — a citation is a wikilink, no cross-domain dependencies established
+- Layered placement: immutable identity facts go to the static layer; drifting interests and habits go to the dynamic layer with stale_after (renewed as observed)
+- An assertion = one line of concrete, verifiable claim + inline evidence wikilink ('prefers concise Chinese replies' beats 'likes brevity'); a single incremental assertion is not directly promoted to a preference — preferences are patterns aggregated within the page
+- Convergence-style updates: when a new value replaces an old one, a trace is left in the body (single line: who changed what, when); full-page rewrites are limited to profile construction/consolidation (preview shown, awaiting confirmation)
+- First creation: the first trigger self-creates the page (frontmatter: type: profile + generated, dynamic layer carries stale_after), independent of any initialization mechanism
+- Diary-type assets record only meta-signals (presence, cadence); content never enters the profile (the exemption followed mapping)
+- Privacy red line: profile content is instance data, never entering the framework repo or test-repo
+- Cognition bridge registration (a domain-plugin-side action, disclosed on this side): when a domain cognition plugin creates its archive and the profile is present, maintain one line in the profile's `## Domain Cognition` section (domain name + path-form wikilink); if the profile is absent, skip without proxy-creating it (on-demand bridge absence tolerance); multiple courses and archives register via the path-form wildcard (bb: <term>/<course> form)
+<!-- /usage:user-profile -->
+
+<!-- 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/query/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: query
+owner: framework
+consumes: [log]
+description: "Retrieve from the wiki and answer synthetically: hot cache → index → grep → read pages, producing answers with wikilink citations. Triggers on: query, what do you know about, what is, explain, find in wiki, 检索."
+---
+
+# query: retrieval
+
+Read-mostly; the only write action is one log line (a read signal). Layered progression — the cheapest goes first.
+
+## Scope
+
+Read: hot, index, tags, pages
+Write: log (one line only, type "query")
+
+## Read Order
+
+1. wiki/hot.md (recent context, cheapest)
+2. wiki/index.md / wiki/tags.md (directory and tag indexes)
+3. grep (path / title / body keywords)
+4. Read specific pages to confirm (≤3-5 pages per query)
+
+## Answer Rules
+
+- 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); page names are preserved as wikilinks
+- Cite sources inline
+- Explicitly flag contradictions with existing repository content
+
+## Not For
+
+- Do not read the repository for general programming questions (training data already covers them)
+- Do not read the repository for content already in the conversation or project files
+
+## Wrap-up
+
+- Write one log line (a read signal — this is how read popularity becomes measurable): see the log block of the injection region for how to call it
+- A log line is a data-zone change: commit immediately per the commit discipline (`检索: <topic>`, see `.meta/protocol/actions.md`); do not batch up
+
+## 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: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 -->