owfadev 0.0.1 → 0.3.0

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

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