owfadev 0.0.1 → 0.3.1

package/.meta/scripts/wikilib.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Wiki page-service load-bearing piece: frontmatter parsing and page traversal, assembled into ctx for the attached-audit runtime.
+
+Plugin attached-audit scripts do not import this module themselves —
+wiki_plugin_kernel.audit scans wiki/ in a single pass and puts the (relative path,
+frontmatter, body) list into ctx.pages for everyone to share (frugal invocation).
+The same minimal YAML subset as wiki_plugin_kernel.parse_manifest, but with a
+different tolerance policy: manifests fail loudly (protocol artifacts), page
+frontmatter skips bad lines (user content must not crash attached audits over
+format blemishes). Keys are lenient (anything non-blank and colon-free):
+block-mapping subkeys may be directory names, Chinese, etc. (a proven need of the
+structure declaration page); top-level protocol fields remain ASCII.
+"""
+import os
+import re
+
+
+def _strip_quotes(s):
+    return s[1:-1] if len(s) >= 2 and s[0] == '"' and s[-1] == '"' else s
+
+
+def _strip_comment(s):
+    return re.split(r"\s+#", s, maxsplit=1)[0].strip()
+
+
+def parse_frontmatter(text):
+    """Parse the minimal YAML subset inside the --- fence; returns an empty dict without a fence, skips bad lines."""
+    m = re.match(r"^---\n(.*?)\n---", text, re.S)
+    if not m:
+        return {}
+    data, target = {}, None
+    for raw in m.group(1).splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        if raw.startswith("  - "):
+            item = _strip_quotes(_strip_comment(raw.strip()[2:]).strip())
+            if not isinstance(data.get(target), list):
+                data[target] = []
+            data[target].append(item)
+            continue
+        mm = re.match(r"^(\s*)([^:\s][^:]*):\s*(.*)$", raw)
+        if not mm:
+            continue
+        key, val = mm.group(2), _strip_comment(mm.group(3))
+        if mm.group(1):
+            if not isinstance(data.get(target), dict):
+                data[target] = {}
+            data[target][key] = _strip_quotes(val)
+        else:
+            target = key
+            if val == "":
+                data[key] = None
+            elif val.startswith("[") and val.endswith("]"):
+                inner = val[1:-1].strip()
+                # strip whitespace before unquoting tokens: in [ai, llm] the second item carries a leading space; not stripping it fragments the vocabulary
+                data[key] = ([_strip_quotes(v.strip()) for v in inner.split(",") if v.strip()]
+                             if inner else [])
+            else:
+                data[key] = _strip_quotes(val)
+    return data
+
+
+def walk_pages(root):
+    """Walk all md pages under wiki/, yielding (wiki-relative path, frontmatter dict, body str)."""
+    wiki = os.path.join(root, "wiki")
+    for dirpath, dirs, files in os.walk(wiki):
+        dirs.sort()
+        for fn in sorted(files):
+            if not fn.endswith(".md"):
+                continue
+            p = os.path.join(dirpath, fn)
+            try:
+                text = open(p, encoding="utf-8").read()
+            except UnicodeDecodeError:
+                text = open(p, encoding="utf-8", errors="replace").read()
+            m = re.match(r"^---\n.*?\n---\n?", text, re.S)
+            rel = os.path.relpath(p, wiki).replace(os.sep, "/")
+            yield rel, parse_frontmatter(text), (text[m.end():] if m else text)

package/.meta/tests/test_install_preflight.py

@@ -0,0 +1,177 @@
+"""Offline install regressions; synthetic packages and disposable instances only.
+
+Run: python -m unittest discover -s .meta/tests -p test_install_preflight.py -v
+"""
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+
+FRAMEWORK = Path(__file__).resolve().parents[2]
+
+
+class InstallPreflightTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory(prefix="kernel-install-test-")
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name) / "instance"
+        self.root.mkdir()
+        for directory in (".meta", ".agents"):
+            shutil.copytree(FRAMEWORK / directory, self.root / directory,
+                            ignore=shutil.ignore_patterns("__pycache__", "tests", "smoke-tmp"))
+        (self.root / "AGENTS.md").write_text(
+            "# Synthetic instance\n<!-- wiki-inject:start -->\n<!-- wiki-inject:end -->\n",
+            encoding="utf-8")
+        self.source = Path(self.temp.name) / "source"
+        self.source.mkdir()
+        self.env = dict(os.environ, PYTHONDONTWRITEBYTECODE="1", PYTHONIOENCODING="utf-8")
+        self.env.pop("PYTHONPATH", None)
+        result = self.run_kernel("all")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def run_kernel(self, *args):
+        return subprocess.run(
+            [sys.executable, str(self.root / ".meta/scripts/wiki_plugin_kernel.py"), *args],
+            cwd=self.root, env=self.env, capture_output=True, text=True, encoding="utf-8")
+
+    def run_code(self, code):
+        prefix = "import sys; sys.path.insert(0, '.meta/scripts'); import wiki_plugin_kernel as k; "
+        return subprocess.run([sys.executable, "-c", prefix + code], cwd=self.root,
+                              env=self.env, capture_output=True, text=True, encoding="utf-8")
+
+    def manifest(self, name, inject, depends="[domain, wiki, trust, log]", tier=None):
+        directory = self.source / name
+        directory.mkdir(exist_ok=True)
+        dependencies = "".join(f"  - {item.strip()}\n" for item in depends.strip("[]").split(","))
+        text = (f"id: {name}\nschema_version: 1\nversion: 0.1\nupdated: 2026-10-24\n"
+                f"depends:\n{dependencies}attachment: []\nfields:\n"
+                f"inject: {json.dumps(inject, ensure_ascii=False)}\n")
+        if tier:
+            text += f"inject_tier: {tier}\n"
+        (directory / "PLUGIN.yaml").write_text(text, encoding="utf-8")
+        (directory / "PLUGIN.md").write_text("# Synthetic test plugin\n", encoding="utf-8")
+
+    def package(self, inject="Synthetic test", members="[probe]"):
+        (self.source / "PKG.yaml").write_text(
+            "schema_version: 1\nid: probe\nversion: 0.1\ncompat: '>= 0.3'\n"
+            f"members: {members}\ndepends: [framework]\n", encoding="utf-8")
+        self.manifest("probe", inject)
+
+    def install(self, *extra):
+        return self.run_kernel("install", "probe", "--path", str(self.source), *extra)
+
+    def snapshot(self):
+        return {str(path.relative_to(self.root)): hashlib.sha256(path.read_bytes()).hexdigest()
+                for path in self.root.rglob("*") if path.is_file()}
+
+    def budget_text(self, extra=0):
+        result = self.run_code(
+            "p,e=k.load_plugins(); assert not e; b,_=k.build_inject_blocks(p); "
+            "print(k.INJECT_BUDGET-sum(len(x.encode('utf-8')) for x in b))")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        overhead = len("<!-- plugin:probe v0.1 -->\n- \n<!-- /plugin:probe -->".encode("utf-8"))
+        room = int(result.stdout.strip()) - overhead + extra
+        return "界" * (room // 3) + "x" * (room % 3)
+
+    def test_over_budget_leaves_all_instance_state_unchanged(self):
+        self.package(self.budget_text(extra=1))
+        # These would all land or change if rejection happened after copy/staging.
+        for relative in ("connectors/test-connector/file.txt", "command/test-command/file.txt",
+                         "migrations/init.md"):
+            path = self.source / relative
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text("Synthetic payload", encoding="utf-8")
+        ledger = self.root / ".meta/migrations/pending.json"
+        ledger.parent.mkdir(exist_ok=True)
+        ledger.write_text(json.dumps({"probe": {"kind": "teardown", "items": []}}), encoding="utf-8")
+        before = self.snapshot()
+        result = self.install()
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("over the 16384 B budget", result.stdout)
+        self.assertIn("preflight failed", result.stdout)
+        self.assertEqual(self.snapshot(), before)
+        self.assertTrue((self.source / "probe/PLUGIN.yaml").exists())
+
+    def test_exact_utf8_budget_installs_and_converges(self):
+        self.package(self.budget_text())
+        result = self.install()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertIn("plugin:probe", (self.root / "AGENTS.md").read_text(encoding="utf-8"))
+        result = self.run_kernel("all")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def test_without_cascade_uses_only_the_installed_subset(self):
+        self.package(members="[probe, optional, child]")
+        self.manifest("optional", "界" * 6000, depends="[probe]")
+        self.manifest("child", "界" * 6000, depends="[optional]")
+        result = self.install("--without", "optional")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        installed = self.root / ".meta/plugins/domains/probe"
+        self.assertFalse((installed / "optional").exists())
+        self.assertFalse((installed / "child").exists())
+        self.assertEqual(self.run_kernel("validate").returncode, 0)
+
+    def test_member_tier_does_not_consume_injection_budget(self):
+        self.package(members="[probe, member]")
+        self.manifest("member", "界" * 6000, depends="[probe]", tier="member")
+        result = self.install()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertNotIn("plugin:member", (self.root / "AGENTS.md").read_text(encoding="utf-8"))
+
+    def test_duplicate_installed_id_is_rejected_before_copy(self):
+        self.package(members="[probe, language]")
+        self.manifest("language", "Duplicate", depends="[probe]")
+        before = self.snapshot()
+        result = self.install()
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("duplicate plugin id", result.stdout)
+        self.assertEqual(self.snapshot(), before)
+
+    def test_post_copy_binding_failure_returns_nonzero_and_warns(self):
+        self.package()
+        path = self.source / "probe/PLUGIN.yaml"
+        path.write_text(path.read_text(encoding="utf-8") + "commands:\n  - missing-command\n", encoding="utf-8")
+        result = self.install()
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("install incomplete", result.stdout)
+        self.assertIn("missing command", result.stdout)
+        self.assertTrue((self.root / ".meta/plugins/domains/probe/PKG.yaml").exists())
+
+    def test_projection_failure_returns_nonzero(self):
+        self.package()
+        (self.root / "AGENTS.md").write_text("# Missing injection markers\n", encoding="utf-8")
+        result = self.install()
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("projection failed (do_inject)", result.stdout)
+        self.assertIn("install incomplete", result.stdout)
+
+    def test_semantic_init_stays_pending_without_becoming_mechanical_failure(self):
+        self.package()
+        migration = self.source / "migrations/init.md"
+        migration.parent.mkdir()
+        migration.write_text("# Synthetic manual initialization\n", encoding="utf-8")
+        result = self.install()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertIn("semantic migration staged", result.stdout)
+        result = self.run_kernel("validate")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("pending semantic migration", result.stdout)
+
+    def test_deploy_failure_is_propagated(self):
+        self.package()
+        result = self.run_code(
+            "k.do_deploy=lambda: False; "
+            f"sys.exit(k.do_install('probe', ['--path', {str(self.source)!r}]))")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("deployment failed", result.stdout)
+        self.assertIn("install incomplete", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 AIE3905-Wuwa
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 AIE3905-Wuwa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,23 +1,104 @@
-# owfadev
+# OWFA — One Workspace For All (agents)
 
-**One Workspace For All (agents).**
+> English | [简体中文](README.zh-CN.md)
 
-This is the **interim distribution package** for the owfa project.
+> **OWFA** is the project; **OWFA Core** is the framework body (formerly `vault-wiki`); **OWFA CLI** is the installer. The public home is moving to **`owfadev/owfa`** — `github.com/owfa` is an unrelated organization. The npm name `owfa` is under application; see [The name](#the-name).
 
-## Why `owfadev` and not `owfa`?
+**OWFA** (One Workspace For All agents) is an open-source agent workspace: out-of-the-box on first install, continuously maintainable over time, and pluginized end to end. One workspace — the directory you own, holding `vault/` (real assets), `wiki/` (md proxies and native notes) and `AGENTS.md` (the constitution) — is the standing context that every agent you use re-enters instead of being re-introduced each session. The agent reads and writes with zero priors per the SASU-L disclosure order; md plus plain files are the foundation, and Obsidian and friends are replaceable viewers. Behavior is personalizable through a living user profile, and new capabilities land as plugins — every plugin ships through the registry with a human-review gate, so contributions are welcome: build a domain plugin for the sources you use and file a one-line PR to list it (see [Contributing](#contributing)).
 
-npm's package-name similarity policy currently blocks publishing the bare name `owfa`
-(deemed too similar to the existing packages `ow` and `ora`). A name-review appeal is
-filed with npm. Until it resolves, `owfadev` is the official distribution channel:
+> Status: **alpha** — capability-wise a prototype matured by six weeks of real daily use (born 2026-09-08, validated by two rounds of real operation plus a cold-start disclosure audit, the bb course family live across four courses); distribution-wise v0.3 is the first shape others can install — covered by exactly one fresh-instance acceptance run, zero outside users. Beta gate: behavior contracts (#34) landed · both members running real installs · the legacy-instance conversion walked through · the acceptance script replayable green. `.meta/VERSION` tracks the kernel contract, not product maturity — stage labels live here and in release notes. Universalization and matrix testing remain deferred. Converted from personal use to a team project on 2026-10-02. Docs language switched to English on 2026-10-06 (historical Chinese log entries preserved as-is). 2026-10-12: repo transferred to the GitHub org **AIE3905-Wuwa**; the standardization-and-split improvement phase opened — package binding landed (core 20 + 5 domain packages, see [.meta/docs/packages.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/packages.md)); dev rules now live in [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md). 2026-10-13: VERSION 0.3 (tag v0.3) — registry discovery/install, subset installs (--without), upgrade chaining, teardown (x->0) closing the migration algebra, the instance git contract; validated end-to-end by a fresh-instance acceptance run. 2026-10-25: the framework body gets a distribution channel of its own — npm CLI `owfa` (`init` / `upgrade` / `doctor` / `add`), closing the "clone + copy two trees + hand-write AGENTS.md" gap (issues #45/#46); the npm name `owfa` is frozen under the registry's similarity policy and is under application, with `owfadev` as the fallback namespace.
 
-- If the appeal succeeds, this package will be deprecated in favor of `owfa`.
-- If not, `owfadev` stays the distribution name.
+## The name
 
-## What's coming
+**OWFA — One Workspace For All (agents).** One workspace — the directory you own, holding `vault/`, `wiki/`, `AGENTS.md` and the framework body — that every agent you use re-enters instead of being re-introduced each session. *All* means all of *your* agents, not all people and not a hosted service; the human stays the owner and the audit anchor. `vault-wiki` retires from the public surface: public copy says **OWFA** (or **OWFA Core**), the GitHub home moves to **`owfadev/owfa`**, and `owfa` is the name the CLI ships under. That last address is not free yet — npm froze `owfa` as too similar to `ow`/`ora`; an application is in progress, and `owfadev` is the fallback package. Full rationale, layers and collision policy: [`.meta/docs/naming.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/naming.md).
 
-An agent knowledge-base framework: `vault/` holds real assets, `wiki/` keeps md proxies
-and native notes, and an AI coding agent tends it for you (map / save / query / check).
-Bootstrap target: `npx owfadev init`.
+## What it does
+
+Let an AI coding agent run a "personal wiki" for you:
+
+- Drop assets into `vault/`, any format — md, txt, csv, pdf, images. The **map** command registers each as an md proxy page under `wiki/vault/`, with SHA-256, metadata and links
+- Insights and decisions from conversations are distilled by the **save** command into native notes under `wiki/notes/`; session backbone pages go to `wiki/sessions/`
+- The **query** command reads the hot cache and indexes first, then answers with wikilink-cited results
+- Index, tags, hot cache and the run log are all maintained automatically by the derived layer; the **check** command audits library health; the **plugin** command installs/uninstalls structural plugins
+- External sources attach as domains: lark and email land as pointers or archive pages; calendar manages the timeline; project manages project containers; bb pulls courseware, assignments and grades via bb-cli; bilibili answers on demand via bili-cli (search/details/favorites/UP tracking; video summaries and reviews archived on explicit request; low-risk write whitelist behind explicit user verbs). Translation happens outside domains; inside the wiki everything interlinks
+- The **profile** command maintains a living cognition file about the user: assertions carry evidence, preferences expire; read it before any personalization
+- The **teach** command explains per the cognition profile — skim or quiz the known, unpack the unknown; significant Q&A settles into ai notes
+- The **quiz** command generates practice from a scope plus optional samples; grading flows back into the cognition profile
+- The **track** command reads/writes per-course user.md learning state; teach and quiz usage mounts here
+
+## Core concepts
+
+| Concept | Definition |
+|---|---|
+| wiki | the md world, the inner side of the inner/outer divide: per-domain projections + native notes + derived layer |
+| domain | the adapter contract for an information source outside the wiki. vault is the default domain; lark, project, email, bb, bili are domains too |
+| vault | the default domain — the real-asset repository; command side append-only, deletion & editing belong to the human |
+| SASU-L | the disclosure paradigm: the agent learns only via system prompt, AGENTS.md, Skills, user's words, loop |
+
+## Layout
+
+| Directory | Contents |
+|------|------|
+| `.meta/` | Prototype core, two-level plugin layout: `plugins/core/` (20 framework plugins — the two conceptual roots domain and wiki, cross-cutting pieces, and the explicit vault/mapping/structure constitutional exception) + `plugins/domains/<pkg>/` (one package per directory: `PKG.yaml` + family masters — cuhksz 8, lark 4, email, bili, project). Directory boundary == tier boundary == package boundary; `PKG.yaml` declares the roster and the kernel reconciles it against the family closure; `.meta/VERSION` anchors the framework version (package `compat` floors checked against it). Injection order = dependency topology + alphabetical; the AGENTS injection region is tiered — member-tier domain pieces exit it (family roster + skills + on-demand manifest reads carry exposure) under a kernel byte budget; global plugins may declare bridges, and mandatory bridges are kernel-verified. Also 13 command masters, protocol artifacts — registry, actions, experiments — and the mechanical scripts wiki_plugin_kernel, pipeline, wikilib, pure stdlib with zero deps |
+| `connectors/` | Connector masters: deployment-side CLI factual interface + skill usage disclosure. `connectors/*/SKILL.md` lands in `.agents/skills/` via kernel deploy; currently bb-cli, sis-cli, mail-cli, bili-cli. Connectors ride with their packages in `PKG.yaml` — physical relocation into the per-package repos happens at the split round |
+| Packages | The index lives in the [registry](https://github.com/owfadev/registry) (Obsidian-model: self-hosted packages, one-line PR is the listing gate). `kernel install`/`list-remote` resolve against it; unindexed repos stay installable with `--yes` (trust: unknown). The org repos `pkg-cuhksz` / `pkg-lark` / `pkg-email` / `pkg-bili` / `pkg-project` / `pkg-github` hold the packages, split with full file lineage |
+| `.agents/skills/` | Deployment copies of command & connector skills (framework commands after the split; connector skills arrive with their packages) |
+| `bin/` + `templates/` + `package.json` | The npm channel: `owfa` CLI, AGENTS seed, package manifest. `test/` and `scripts/` are development-only and never ship |
+| `test-repo/` | Local test sandbox — untracked since 2026-10-13 (owner re-ruling; a fresh clone carries none of it). A scratch deployment for experiments needing an AGENTS.md context; setup and rules in [`.meta/docs/sandbox.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/sandbox.md). The framework repo itself carries no AGENTS.md — library posture; dev rules live in [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md) |
+| `.meta/docs/` | Human docs: `intro.md` introduction, `mechanics.md` mechanics, `usage.md` usage guide, `deployment.md` full guide / `quickstart.md` five-minute path, `instance-git.md` the instance-side git minimal contract, `research-*.md` research files — direct links at the end. Authoritative mechanics live in the kernel reference skill; docs do not mirror mechanics |
+
+## Contributing
+
+Contributions are welcome, and plugins are the intended surface: a new capability is a new plugin, not a fork of the framework. Three paths, smallest first — a connector skill for a CLI you use, a domain plugin that adapts an external source to the wiki (see [`developer.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/developer.md) for the three-path table and the dev loop), or an improvement to core. Domain packages self-host in their own repos; listing is a one-line PR to the [registry](https://github.com/owfadev/registry), which is the human-review trust gate. Bug reports and behavior questions go through issues; the framework body itself takes PRs.
+
+## Collaboration
+
+This repository is a team project: three members with write access, everything through PRs (1 approving review to merge, `enforce_admins` on); the owner holds final say on repo settings, permissions and charter/kernel changes. Data red lines, commit flow and version discipline are summarized in [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md) — the authoritative dev rules; the change trail is git history + PRs + issues (the repo keeps no run log).
+
+## Getting started
+
+Two ways in. **Channel (recommended):** `npx owfa init my-workspace` — Node 16.7+ for the installer, Python 3.9+ for Core; nothing to clone (`npx owfadev init` is the fallback while the npm name is under application). **Manual:** clone this repository and follow the five steps in [quickstart.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/quickstart.md), then `python .meta/scripts/wiki_plugin_kernel.py all`. Full guide, including packages and upgrades: [deployment.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/deployment.md).
+
+Prerequisites: Python 3.9+, pure stdlib, no install needed for the framework itself (connectors carry their own deps); Node 16.7+ only for the npm channel; git recommended (instance snapshots); an agent environment that reads AGENTS.md and skills, e.g. ZCode; Obsidian optional, viewer only.
+
+Open an agent session at the repository root. AGENTS.md is the constitution, containing the plugin injection region; the thirteen commands trigger by natural language: **map / save / profile / query / check / plugin / lark-map / bb-map / asset-read / kernel reference / teach / quiz / track** — map, save, profile, query, check, plugin, lark-map, bb-map, asset-read, wiki_plugin_kernel, bb-teach, bb-quiz, bb-track; masters live in `.meta/command/`. Put a file into `vault/` and say "map" to the agent — that is the first use.
+
+## Deployment
+
+OWFA has three layers: **OWFA CLI** (the installer, never copied into the workspace), **OWFA Core** (`.meta/` + `.agents/skills/`, the thing that is installed), and the **kernel** (a pure-stdlib Python script inside Core — there is no separate kernel install; Python 3.9+ runs it). Domain packages under `.meta/plugins/domains/<pkg>/` are optional.
+
+```bash
+npx owfa init my-workspace        # target name; npx owfadev init while the application is pending
+cd my-workspace
+npx owfa doctor                   # target: python / framework / markers / kernel validate (npx owfadev doctor for the fallback)
+npx owfa list                     # registry catalog
+npx owfa add cuhksz               # optional package
+npx owfa upgrade                  # later: replace the framework trees, preserve instance state
+```
+
+While the name is under application, substitute `npx owfadev` for every `npx owfa` command above (or install either package globally; both expose the `owfa` bin).
+
+`init` is additive: existing content is untouched, an existing `AGENTS.md` is preserved and only the injection region is appended. `upgrade` replaces `.meta/` and `.agents/skills/` (instance data is never touched) and keeps the kernel's migration ledger, journal and registry cache.
+
+- Full deployment guide (components, channels, packages, upgrades, troubleshooting): [`.meta/docs/deployment.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/deployment.md)
+- Five-minute path: [`.meta/docs/quickstart.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/quickstart.md)
+- Channel design and release runbook: [`.meta/docs/distribution.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/distribution.md)
+
+## Doc pointers
+
+- [.meta/docs/deployment.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/deployment.md) — deployment guide: components, channels, first run, packages, upgrades, troubleshooting
+- [.meta/docs/naming.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/naming.md) — the name: canonical expansion, what each word commits to, two names two jobs, objections, collision policy
+- [.meta/docs/distribution.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/distribution.md) — the npm channel: commands, artifacts, version invariant, release runbook, security posture
+- [.meta/docs/packages.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/packages.md) — package mechanism and design rationale: layout, PKG.yaml, invariants, versions, uninstall contract, decision ledger
+- [.meta/docs/developer.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/developer.md) — developer guide: where a plugin lands (the three-path table), the dev loop, registration and discovery
+- [.meta/docs/agents-example.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/agents-example.md) / [.meta/docs/log-example.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/log-example.md) — instance seeds for AGENTS.md and log.md (the framework repo itself carries neither)
+- [.meta/docs/intro.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/intro.md) — introduction: why this framework, narrative & lineage
+- [.meta/docs/mechanics.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/mechanics.md) — mechanics: each mechanism one level deeper, with a bb-family walkthrough; read before touching the framework
+- [.meta/docs/usage.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/usage.md) — usage guide: the three work loops (library keeping, course learning, collaborative development)
+- [.meta/docs/quickstart.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/quickstart.md) — five-minute path: one command or the manual five steps, then first run
+- `.meta/protocol/` — field registry, action discipline, disclosure paradigm
+
+## License
+
+MIT — see [LICENSE](https://github.com/owfadev/owfa/blob/master/LICENSE).
 
-- Source: <https://github.com/AIE3905-Wuwa/vault-wiki>
-- Status: alpha. Version will mirror the framework's `VERSION` once the real CLI lands.

package/README.zh-CN.md

@@ -0,0 +1,103 @@
+# OWFA — One Workspace For All (agents)
+
+> [English](README.md) | 简体中文
+
+> **OWFA** 是项目名；**OWFA Core** 是框架本体（原 `vault-wiki`）；**OWFA CLI** 是安装器。公开主页为 **`owfadev/owfa`**——`github.com/owfa` 是无关组织。npm 包名 `owfa` 正在申请中，详见[「关于命名」](#关于命名)。
+
+**OWFA**（One Workspace For All agents）是一个开源的 agent 工作区：开箱即用、可持续维护、端到端插件化。一个工作区——你拥有的那个目录，装着 `vault/`（真实资产）、`wiki/`（md 投影与原生笔记）和 `AGENTS.md`（章程）——是你所有 agent 反复进入的常驻上下文，而不是每次会话重新自我介绍。agent 按 SASU-L 披露次序零先验地读写；md 与纯文本文件是地基，Obsidian 等只是可替换的查看器。行为通过一份活的用户画像个性化，新能力以插件落地——每个插件都经 registry 的人工审核门发布，欢迎贡献：为你使用的信息源写一个域插件，向 registry 提一行 PR 即可上架（见[参与贡献](#参与贡献)）。
+
+> 状态：**alpha**——能力面是经六周真实日常使用打磨出的原型（生于 2026-09-08，经两轮实际运营与一次冷启动披露审计检验，bb 课程家族在四门课真实运行）；分发面 v0.3 是首个可安装形态——经一次全新实例验收，尚无外部用户。Beta 门槛：行为契约（#34）落地 · 两位成员真实装机 · 旧实例转换走通 · 验收脚本可重放绿。`.meta/VERSION` 锚定的是内核契约而非产品成熟度——阶段标签在这里与 release notes。2026-10-02 转为团队项目。文档语言 2026-10-06 起切换为英文。2026-10-25：框架本体有了自己的分发通道——npm CLI `owfa`（`init` / `upgrade` / `doctor` / `add`），补上「clone + 拷两棵树 + 手写 AGENTS.md」的缺口（issues #45/#46）；npm 名 `owfa` 因相似性策略冻结，申请中，`owfadev` 为兜底命名空间。
+
+## 关于命名
+
+**OWFA — One Workspace For All (agents)。** 一个工作区——你拥有的目录，装着 `vault/`、`wiki/`、`AGENTS.md` 与框架本体——你使用的每一个 agent 都重新进入它，而不是每次会话重新认识它。*All* 指的是*你的*所有 agent，不是所有人，也不是托管服务；人始终是所有者与审计锚点。`vault-wiki` 退出公开面：公开文案称 **OWFA**（或 **OWFA Core**），GitHub 家在 **`owfadev/owfa`**，CLI 以 `owfa` 之名发布。npm 地址尚未空闲——npm 以「与 `ow`/`ora` 过于相似」冻结了 `owfa`，申诉进行中，`owfadev` 为兜底包。完整的理据、分层与撞名对策：[`.meta/docs/naming.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/naming.md)。
+
+## 它做什么
+
+让 AI 编码 agent 替你经营一座「个人 wiki」：
+
+- 资产随手丢进 `vault/`，任何格式——md、txt、csv、pdf、图片。**map** 命令把每件资产登记为 `wiki/vault/` 下的 md 投影页，带 SHA-256、元数据与链接
+- 对话中的洞见与决策由 **save** 命令蒸馏为 `wiki/notes/` 下的原生笔记；会话骨架页进 `wiki/sessions/`
+- **query** 命令先读热缓存与索引，再以 wikilink 引用作答
+- 索引、标签、热缓存与运行日志由派生层自动维护；**check** 命令体检库健康；**plugin** 命令装卸结构插件
+- 外部信息源以域接入：lark 与 email 落为指针或归档页；calendar 管时间线；project 管项目容器；bb 经 bb-cli 拉课件、作业与成绩；bilibili 经 bili-cli 按需应答（搜索/详情/收藏/UP 追更；视频摘要与评审经显式请求归档；低风险写白名单须用户显式动词）。翻译发生在域外；域内一切互链
+- **profile** 命令维护一份关于用户的活认知档案：断言带证据，偏好会过期；任何个性化决策前先读它
+- **teach** 命令按认知档案讲解——熟点略讲或抽测，生点拆解；重要问答沉淀进 ai notes
+- **quiz** 命令按范围加可选样本出题；批改结果回流认知档案
+- **track** 命令读写每门课的 user.md 学习状态；teach 与 quiz 的使用挂载于此
+
+## 核心概念
+
+| 概念 | 定义 |
+|---|---|
+| wiki | md 世界，内外之分的内侧：各域投影 + 原生笔记 + 派生层 |
+| domain | wiki 之外信息源的适配器契约。vault 是默认域；lark、project、email、bb、bili 也是域 |
+| vault | 默认域——真实资产仓库；命令侧只增不删，删除与修改的自由属于人 |
+| SASU-L | 披露范式：agent 只经系统提示、AGENTS.md、Skills、用户的话与循环来学习 |
+
+## 目录结构
+
+| 目录 | 内容 |
+|------|------|
+| `.meta/` | 原型核心，两级插件布局：`plugins/core/`（20 个框架插件——domain 与 wiki 两个概念根、横切件，以及 vault/mapping/structure 的明示章程例外）+ `plugins/domains/<pkg>/`（一包一目录：`PKG.yaml` + 家族母本——cuhksz 8、lark 4、email、bili、project）。目录边界 == 层级边界 == 包边界；`PKG.yaml` 声明名册，内核对账家族闭包；`.meta/VERSION` 锚定框架版本（包 `compat` 下限对它校验）。注入次序 = 依赖拓扑 + 字典序；AGENTS 注入区分层——成员级域件退出注入区（家族名册 + 技能 + 按需 manifest 读取承担曝光），受内核字节预算约束；全局插件可声明桥，必依桥由内核校验。另有 13 个命令母本、协议工件（registry、actions、experiments）与机械脚本 wiki_plugin_kernel、pipeline、wikilib——纯标准库零依赖 |
+| `connectors/` | 连接器母本：部署侧 CLI 事实接口 + 技能使用披露。`connectors/*/SKILL.md` 经内核 deploy 落入 `.agents/skills/`；现有 bb-cli、sis-cli、mail-cli、bili-cli。连接器随各自包的 `PKG.yaml` 走 |
+| Packages | 索引在 [registry](https://github.com/owfadev/registry)（Obsidian 模式：包自托管于各自仓，一行 PR 即上架门）。`kernel install`/`list-remote` 对它解析；未入索引的仓 `--yes` 可装（trust: unknown）。组织仓 `pkg-cuhksz` / `pkg-lark` / `pkg-email` / `pkg-bili` / `pkg-project` / `pkg-github` 承载各包，带完整文件谱系拆分 |
+| `.agents/skills/` | 命令与连接器技能的部署副本（拆分后框架命令在此；连接器技能随包到达） |
+| `bin/` + `templates/` + `package.json` | npm 通道：`owfa` CLI、AGENTS 种子、包清单。`test/` 与 `scripts/` 仅供开发，不随包发布 |
+| `test-repo/` | 本地测试沙盒——2026-10-13 起不入 git（owner 裁定；全新 clone 不含它）。需要 AGENTS.md 上下文的实验用临时部署；设置与规则见 [`.meta/docs/sandbox.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/sandbox.md)。框架仓自身不带 AGENTS.md——库姿态；开发规则在 [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md) |
+| `.meta/docs/` | 人读文档：`intro.md` 导论、`mechanics.md` 机制、`usage.md` 使用指南、`deployment.md` 全指南 / `quickstart.md` 五分钟路径、`instance-git.md` 实例侧 git 最小契约、`research-*.md` 研究文件——文末直链。权威机制在内核参考 skill；文档不复写机制 |
+
+## 参与贡献
+
+欢迎贡献，插件是预定贡献面：新能力是新插件，不是 fork 框架。三条路径，由小到大——为你使用的 CLI 写一个连接器技能；写一个把外部信息源适配进 wiki 的域插件（三路径表与开发循环见 [`developer.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/developer.md)）；或改进 core。域包自托管于各自仓；上架 = 向 [registry](https://github.com/owfadev/registry) 提一行 PR，那是人工审核的信任门。Bug 与行为问题走 issues；框架本体收 PR。
+
+## 协作
+
+本仓是团队项目：三名成员有写权限，一切经 PR（1 个 approving review 可合，`enforce_admins` 开启）；owner 对仓库设置、权限与章程/内核变更有最终决定权。数据红线、提交流程与版本纪律 summarized 在 [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md)——权威开发规则；变更轨迹是 git 历史 + PR + issues（本仓不留运行日志）。
+
+## 快速开始
+
+两条入口。**通道（推荐）：** `npx owfa init my-workspace`——安装器要 Node 16.7+，Core 要 Python 3.9+；无需 clone（npm 名申请期间用 `npx owfadev init` 兜底）。**手动：** clone 本仓并按 [quickstart.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/quickstart.md) 的五步走，然后 `python .meta/scripts/wiki_plugin_kernel.py all`。含包与升级的全指南：[deployment.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/deployment.md)。
+
+前提：Python 3.9+，纯标准库，框架本身免安装（连接器自带依赖）；仅 npm 通道要 Node 16.7+；推荐 git（实例快照）；一个会读 AGENTS.md 与 skills 的 agent 环境，如 ZCode；Obsidian 可选，仅查看器。
+
+在仓库根开一个 agent 会话。AGENTS.md 是章程，含插件注入区；十三个命令经自然语言触发：**map / save / profile / query / check / plugin / lark-map / bb-map / asset-read / 内核参考 / teach / quiz / track**——map、save、profile、query、check、plugin、lark-map、bb-map、asset-read、wiki_plugin_kernel、bb-teach、bb-quiz、bb-track；母本在 `.meta/command/`。丢一个文件进 `vault/`，对 agent 说「map」——这就是第一次使用。
+
+## 部署
+
+OWFA 有三层：**OWFA CLI**（安装器，绝不拷入工作区）、**OWFA Core**（`.meta/` + `.agents/skills/`，被安装之物）与 **kernel**（Core 内的纯标准库 Python 脚本——没有单独的内核安装；Python 3.9+ 即可运行）。`.meta/plugins/domains/<pkg>/` 下的域包是可选的。
+
+```bash
+npx owfa init my-workspace        # 目标名；申请期间用 npx owfadev init
+cd my-workspace
+npx owfa doctor                   # 体检：python / 框架 / 标记 / kernel validate（兜底用 npx owfadev doctor）
+npx owfa list                     # registry 目录
+npx owfa add cuhksz               # 可选包
+npx owfa upgrade                  # 日后：替换框架树，保留实例状态
+```
+
+名字申请期间，把上面每条 `npx owfa` 换成 `npx owfadev` 即可（或全局安装任一包；两者都暴露 `owfa` 命令）。
+
+`init` 是加法的：既有内容不动，已有 `AGENTS.md` 保留、只追加注入区。`upgrade` 替换 `.meta/` 与 `.agents/skills/`（实例数据永不触碰），保留内核迁移台账、journal 与 registry 缓存。
+
+- 全部署指南（组件、通道、包、升级、故障）：[`.meta/docs/deployment.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/deployment.md)
+- 五分钟路径：[`.meta/docs/quickstart.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/quickstart.md)
+- 通道设计与发布手册：[`.meta/docs/distribution.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/distribution.md)
+
+## 文档索引
+
+- [.meta/docs/deployment.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/deployment.md) — 部署指南：组件、通道、首跑、包、升级、故障
+- [.meta/docs/naming.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/naming.md) — 命名：本义展开、每个词的承诺、两名两职、异议与撞名对策
+- [.meta/docs/distribution.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/distribution.md) — npm 通道：命令、工件、版本不变量、发布手册、安全姿态
+- [.meta/docs/packages.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/packages.md) — 包机制与设计理据：布局、PKG.yaml、不变量、版本、卸载契约、决策台账
+- [.meta/docs/developer.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/developer.md) — 开发者指南：插件落位三路径表、开发循环、注册与发现
+- [.meta/docs/agents-example.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/agents-example.md) / [.meta/docs/log-example.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/log-example.md) — AGENTS.md 与 log.md 的实例种子（框架仓自身两者都不带）
+- [.meta/docs/intro.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/intro.md) — 导论：为什么是这个框架，叙事与谱系
+- [.meta/docs/mechanics.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/mechanics.md) — 机制：每个机制再深一层，附 bb 家族走查；动框架前先读
+- [.meta/docs/usage.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/usage.md) — 使用指南：三种工作循环（库务、课程学习、协作开发）
+- [.meta/docs/quickstart.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/quickstart.md) — 五分钟路径：一条命令或手动五步，然后首跑
+- `.meta/protocol/` — 字段注册表、行动纪律、披露范式
+
+## 许可
+
+MIT——见 [LICENSE](https://github.com/owfadev/owfa/blob/master/LICENSE)。