owfadev 0.3.2 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/.agents/skills/owfa-check/SKILL.md +49 -0
  2. package/.agents/skills/{docs → owfa-docs}/SKILL.md +5 -5
  3. package/.agents/skills/{wiki_plugin_kernel → owfa-kernel}/SKILL.md +13 -12
  4. package/{.meta/command/plugin → .agents/skills/owfa-plugin}/SKILL.md +10 -10
  5. package/.agents/skills/{query → owfa-query}/SKILL.md +5 -6
  6. package/.owfa/VERSION +1 -0
  7. package/.owfa/command/owfa-check/SKILL.md +49 -0
  8. package/{.meta/command/docs → .owfa/command/owfa-docs}/SKILL.md +5 -5
  9. package/{.meta/command/wiki_plugin_kernel → .owfa/command/owfa-kernel}/SKILL.md +13 -12
  10. package/{.agents/skills/plugin → .owfa/command/owfa-plugin}/SKILL.md +10 -10
  11. package/{.meta/command/query → .owfa/command/owfa-query}/SKILL.md +5 -6
  12. package/{.meta → .owfa}/docs/agent-behavior.md +3 -2
  13. package/{.meta → .owfa}/docs/agents-example.md +1 -1
  14. package/{.meta → .owfa}/docs/conversion.md +2 -2
  15. package/{.meta → .owfa}/docs/deployment.md +51 -46
  16. package/{.meta → .owfa}/docs/developer.md +4 -4
  17. package/{.meta → .owfa}/docs/distribution.md +21 -19
  18. package/.owfa/docs/home.md +61 -0
  19. package/{.meta → .owfa}/docs/intro.md +5 -5
  20. package/{.meta → .owfa}/docs/log-example.md +1 -1
  21. package/{.meta → .owfa}/docs/map.md +4 -3
  22. package/{.meta → .owfa}/docs/mechanics.md +11 -11
  23. package/{.meta → .owfa}/docs/naming.md +7 -7
  24. package/{.meta → .owfa}/docs/packages.md +80 -15
  25. package/.owfa/docs/plugin-lifecycle.md +70 -0
  26. package/{.meta → .owfa}/docs/quickstart.md +12 -12
  27. package/{.meta → .owfa}/docs/research-user-profile.md +1 -1
  28. package/{.meta → .owfa}/docs/sandbox.md +3 -3
  29. package/{.meta → .owfa}/docs/usage.md +1 -1
  30. package/{.meta → .owfa}/protocol/actions.md +6 -6
  31. package/.owfa/protocol/registry.yaml +34 -0
  32. package/.owfa/scripts/owfa_home.py +273 -0
  33. package/{.meta/scripts/wiki_plugin_kernel.py → .owfa/scripts/owfa_kernel.py} +521 -77
  34. package/{.meta → .owfa}/scripts/pipeline.py +9 -9
  35. package/.owfa/scripts/wiki_plugin_kernel.py +15 -0
  36. package/{.meta → .owfa}/scripts/wikilib.py +2 -2
  37. package/.owfa/tests/test_capabilities.py +311 -0
  38. package/{.meta → .owfa}/tests/test_install_preflight.py +11 -7
  39. package/.owfa/tests/test_owfa_home.py +127 -0
  40. package/.owfa/tests/test_version_scheme.py +68 -0
  41. package/README.md +32 -24
  42. package/README.zh-CN.md +32 -24
  43. package/bin/owfa.js +483 -65
  44. package/package.json +3 -2
  45. package/payloads/personal/PKG.yaml +15 -0
  46. package/payloads/personal/README.md +7 -0
  47. package/{.meta/plugins/core → payloads/personal}/calendar/PLUGIN.md +1 -0
  48. package/{.meta/plugins/core → payloads/personal}/calendar/PLUGIN.yaml +3 -3
  49. package/{.agents/skills/map → payloads/personal/command/owfa-map}/SKILL.md +9 -9
  50. package/{.meta/command/profile → payloads/personal/command/owfa-profile}/SKILL.md +11 -11
  51. package/{.agents/skills/save → payloads/personal/command/owfa-save}/SKILL.md +10 -10
  52. package/{.meta/plugins/core → payloads/personal}/cron/PLUGIN.md +2 -0
  53. package/{.meta/plugins/core → payloads/personal}/cron/PLUGIN.yaml +3 -3
  54. package/{.meta/plugins/core → payloads/personal}/device/PLUGIN.md +1 -0
  55. package/{.meta/plugins/core → payloads/personal}/device/PLUGIN.yaml +3 -3
  56. package/{.meta/plugins/core → payloads/personal}/domain/PLUGIN.md +2 -0
  57. package/payloads/personal/domain/PLUGIN.yaml +8 -0
  58. package/{.meta/plugins/core → payloads/personal}/hot/PLUGIN.yaml +1 -1
  59. package/{.meta/plugins/core → payloads/personal}/index/PLUGIN.md +1 -0
  60. package/{.meta/plugins/core → payloads/personal}/index/PLUGIN.yaml +4 -4
  61. package/{.meta/plugins/core → payloads/personal}/instance-git/PLUGIN.md +5 -0
  62. package/{.meta/plugins/core → payloads/personal}/instance-git/PLUGIN.yaml +3 -3
  63. package/{.meta/plugins/core → payloads/personal}/language/PLUGIN.md +1 -0
  64. package/{.meta/plugins/core → payloads/personal}/language/PLUGIN.yaml +4 -4
  65. package/{.meta/plugins/core → payloads/personal}/link/PLUGIN.md +1 -0
  66. package/{.meta/plugins/core → payloads/personal}/link/PLUGIN.yaml +3 -3
  67. package/{.meta/plugins/core → payloads/personal}/link/scripts/check.py +1 -1
  68. package/{.meta/plugins/core → payloads/personal}/log/PLUGIN.md +1 -0
  69. package/{.meta/plugins/core → payloads/personal}/log/PLUGIN.yaml +4 -4
  70. package/{.meta/plugins/core → payloads/personal}/mapping/PLUGIN.yaml +1 -1
  71. package/{.meta/plugins/core → payloads/personal}/notes/PLUGIN.md +1 -0
  72. package/{.meta/plugins/core → payloads/personal}/notes/PLUGIN.yaml +4 -4
  73. package/{.meta/plugins/core → payloads/personal}/sessions/PLUGIN.md +2 -1
  74. package/{.meta/plugins/core → payloads/personal}/sessions/PLUGIN.yaml +5 -5
  75. package/{.meta/plugins/core → payloads/personal}/structure/PLUGIN.md +2 -0
  76. package/{.meta/plugins/core → payloads/personal}/structure/PLUGIN.yaml +3 -3
  77. package/{.meta/plugins/core → payloads/personal}/structure/scripts/check.py +1 -1
  78. package/{.meta/plugins/core → payloads/personal}/tag/PLUGIN.md +2 -0
  79. package/{.meta/plugins/core → payloads/personal}/tag/PLUGIN.yaml +3 -3
  80. package/{.meta/plugins/core → payloads/personal}/tag/scripts/check.py +3 -1
  81. package/{.meta/plugins/core → payloads/personal}/tmp/PLUGIN.md +1 -0
  82. package/{.meta/plugins/core → payloads/personal}/tmp/PLUGIN.yaml +3 -3
  83. package/{.meta/plugins/core → payloads/personal}/todo/PLUGIN.md +2 -0
  84. package/{.meta/plugins/core → payloads/personal}/todo/PLUGIN.yaml +6 -5
  85. package/payloads/personal/todo/scripts/check.py +51 -0
  86. package/{.meta/plugins/core → payloads/personal}/trust/PLUGIN.md +1 -0
  87. package/{.meta/plugins/core → payloads/personal}/trust/PLUGIN.yaml +3 -3
  88. package/{.meta/plugins/core → payloads/personal}/user-profile/PLUGIN.md +2 -0
  89. package/{.meta/plugins/core → payloads/personal}/user-profile/PLUGIN.yaml +7 -6
  90. package/payloads/personal/user-profile/scripts/check.py +20 -0
  91. package/{.meta/plugins/core → payloads/personal}/vault/PLUGIN.md +1 -0
  92. package/payloads/personal/vault/PLUGIN.yaml +13 -0
  93. package/{.meta/plugins/core → payloads/personal}/wiki/PLUGIN.md +1 -0
  94. package/payloads/personal/wiki/PLUGIN.yaml +8 -0
  95. package/templates/AGENTS.template.md +2 -2
  96. package/.agents/skills/check/SKILL.md +0 -130
  97. package/.agents/skills/profile/SKILL.md +0 -75
  98. package/.meta/VERSION +0 -1
  99. package/.meta/command/check/SKILL.md +0 -130
  100. package/.meta/command/map/SKILL.md +0 -72
  101. package/.meta/command/save/SKILL.md +0 -94
  102. package/.meta/plugins/core/domain/PLUGIN.yaml +0 -8
  103. package/.meta/plugins/core/vault/PLUGIN.yaml +0 -13
  104. package/.meta/plugins/core/wiki/PLUGIN.yaml +0 -8
  105. package/.meta/protocol/registry.yaml +0 -75
  106. /package/{.meta → .owfa}/command/asset-read/SKILL.md +0 -0
  107. /package/{.meta → .owfa}/docs/research-landscape.md +0 -0
  108. /package/{.meta → .owfa}/protocol/experiments.md +0 -0
  109. /package/{.meta/plugins/core → payloads/personal}/device/scripts/check.py +0 -0
  110. /package/{.meta/plugins/core → payloads/personal}/hot/PLUGIN.md +0 -0
  111. /package/{.meta/plugins/core → payloads/personal}/instance-git/scripts/check.py +0 -0
  112. /package/{.meta/plugins/core → payloads/personal}/language/scripts/check.py +0 -0
  113. /package/{.meta/plugins/core → payloads/personal}/log/scripts/check.py +0 -0
  114. /package/{.meta/plugins/core → payloads/personal}/mapping/PLUGIN.md +0 -0
  115. /package/{.meta/plugins/core → payloads/personal}/mapping/scripts/check.py +0 -0
  116. /package/{.meta/plugins/core → payloads/personal}/sessions/scripts/check.py +0 -0
  117. /package/{.meta/plugins/core → payloads/personal}/trust/scripts/check.py +0 -0
@@ -9,9 +9,9 @@ OWFA has three layers, and only one of them is "installed":
9
9
  | Layer | What it is | Where it lives | Installed? |
10
10
  |---|---|---|---|
11
11
  | **OWFA CLI** | the installer / upgrader (`init`, `upgrade`, `doctor`, `add`, `list`, `pkg`) | npm package, run via `npx` or a global install | no — it stays outside the workspace |
12
- | **OWFA Core** | the framework body: plugins, commands, protocols, kernel, skill copies | `.meta/` + `.agents/skills/` | yes — copied into the workspace |
13
- | **kernel** | the deterministic Python engine (`validate`, `inject`, `registry`, `deploy`, `install`) | `.meta/scripts/wiki_plugin_kernel.py` | no — it ships **inside** Core; there is no separate kernel install |
14
- | **packages** | optional domain extensions (course, lark, email, bili, project…) | `.meta/plugins/domains/<pkg>/` | on demand |
12
+ | **OWFA Core** | the framework body: plugins, commands, protocols, kernel, skill copies | `.owfa/` + `.agents/skills/` | yes — copied into the workspace |
13
+ | **kernel** | the deterministic Python engine (`validate`, `inject`, `registry`, `deploy`, `install`) | `.owfa/scripts/owfa_kernel.py` | no — it ships **inside** Core; there is no separate kernel install |
14
+ | **packages** | optional domain extensions (course, lark, email, bili, project…) | `.owfa/plugins/domains/<pkg>/` | on demand |
15
15
  | **instance** | the workspace you own: `vault/`, `wiki/`, `AGENTS.md`, the framework body | your directory | — |
16
16
 
17
17
  The call chain is one direction:
@@ -29,12 +29,11 @@ my-workspace/
29
29
  ├── wiki/ # the markdown world
30
30
  │ ├── notes/ sessions/ vault/
31
31
  │ └── index.md tags.md hot.md log.md # derived, rebuilt by the pipeline
32
- ├── .meta/ # OWFA Core
33
- │ ├── VERSION # framework anchor (0.3)
32
+ ├── .owfa/ # OWFA Core (kernel-only tree since the v0.4 split)
33
+ │ ├── VERSION # framework anchor (0.4.0)
34
34
  │ ├── scripts/ # kernel + pipeline + wikilib
35
- │ ├── plugins/core/ # 21 framework plugins
36
- │ ├── plugins/domains/ # installed packages (empty until you add one)
37
- │ ├── command/ # command masters
35
+ │ ├── plugins/domains/ # installed packages — the embedded personal suite (21 members) lands here on init; the channel itself ships no plugins
36
+ │ ├── command/ # framework command masters (suite-owned commands ride with their package)
38
37
  │ └── docs/ # this guide and friends
39
38
  └── .agents/skills/ # deployed command/connector skill copies
40
39
  ```
@@ -62,7 +61,7 @@ All channels deploy the same Core tree; pick by environment, not by feature.
62
61
  | npm, target name | `npx owfa init my-workspace` | **name application pending** (npm froze `owfa` as too similar to `ow`/`ora`) |
63
62
  | npm, fallback name | `npx owfadev init my-workspace` | same CLI, bins `owfa` + `owfadev`; to be published if the name is not granted |
64
63
  | git, clone-as-instance | `git clone https://github.com/owfadev/owfa.git my-workspace` | works today |
65
- | git, embed into an existing vault | clone the template elsewhere, copy `.meta/` + `.agents/skills/` | works today |
64
+ | git, embed into an existing vault | clone the template elsewhere, copy `.owfa/` + `.agents/skills/` | works today |
66
65
  | template + instance (developers) | a template clone + a separate instance | see [CONTRIBUTING.md](../../CONTRIBUTING.md) |
67
66
 
68
67
  > Until the npm name is served by the registry, the git channel is the working path. Do not treat `npx owfa` as live before `npm view owfa version` returns a version.
@@ -84,13 +83,14 @@ npx owfadev doctor # fallback: same check through the fallback
84
83
 
85
84
  **Command forms.** `npx <package> <verb>` needs no global install. A global install (`npm i -g owfa` or `npm i -g owfadev`) puts **both** `owfa` and `owfadev` on `PATH`. The rest of this guide writes `owfa <verb>` for the CLI and `kernel …` for the Python engine; substitute `npx owfa` / `npx owfadev` if you are not installing globally.
86
85
 
87
- `init` performs the five manual steps below:
86
+ `init` is two-stage by default (the v0.4 final shape — this is the only shape the channel ships):
88
87
 
89
- 1. copies `.meta/` and `.agents/skills/` from the tarball;
90
- 2. creates `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`;
88
+ 1. copies `.owfa/` and `.agents/skills/` from the tarball and runs `python .owfa/scripts/owfa_kernel.py all` (validate → inject → registry → deploy) over the kernel-only tree;
89
+ 2. installs the embedded **personal suite** (the 21 former core plugins, a vetted copy of the **owfa-personal** package at `payloads/personal/`) offline — its `PKG.yaml` `skeleton:` declaration creates `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`, and its command masters (`owfa-map`, `owfa-profile`, `owfa-save`) deploy with it;
91
90
  3. writes `AGENTS.md` from the seed, or appends **only the injection region** to an existing one (the handwritten part is preserved; half-present markers are refused);
92
- 4. runs `python .meta/scripts/wiki_plugin_kernel.py all` (validate → inject → registry → deploy);
93
- 5. optionally installs packages (`--packages cuhksz,lark`), stopping at the first package that stages a semantic migration.
91
+ 4. optionally installs packages (`--packages cuhksz,lark`), stopping at the first package that stages a semantic migration.
92
+
93
+ `--core none` skips stage 2 (a kernel-only instance: no skeleton, no suite); `--core <pkg-id>` takes the suite from the registry instead of the embedded copy.
94
94
 
95
95
  Useful flags:
96
96
 
@@ -98,7 +98,7 @@ Useful flags:
98
98
  - `--packages a,b` — install packages from the registry during init;
99
99
  - `--force` — re-copy the framework trees over an existing instance, preserving the kernel's migration ledger, journal and registry cache. Instance data (`vault/`, `wiki/`) is never touched.
100
100
 
101
- If the directory already contains `.meta/`, `init` refuses; use `owfa upgrade` (or `--force` deliberately).
101
+ If the directory already contains `.owfa/`, `init` refuses; use `owfa upgrade` (or `--force` deliberately).
102
102
 
103
103
  ### 4.2 git channel — the five manual steps
104
104
 
@@ -114,30 +114,35 @@ rm -rf .git && git init
114
114
  **Embed into an existing vault**: clone the template somewhere else, then copy the two trees into the target root:
115
115
 
116
116
  ```bash
117
- cp -R /path/to/owfa/.meta /path/to/my-workspace/
117
+ cp -R /path/to/owfa/.owfa /path/to/my-workspace/
118
118
  cp -R /path/to/owfa/.agents/skills /path/to/my-workspace/.agents/
119
119
  ```
120
120
 
121
+ Since the v0.4 split the copied tree carries the kernel only — no plugins. Install the embedded suite (it ships inside the clone at `payloads/personal/`) and the skeleton with it:
122
+
123
+ ```bash
124
+ python3 .owfa/scripts/owfa_kernel.py install personal --path /path/to/owfa/payloads/personal
125
+ ```
126
+
121
127
  Then, at the workspace root:
122
128
 
123
129
  1. **Write `AGENTS.md`** — one identity paragraph, one layout paragraph, and the injection markers verbatim from [agents-example.md](agents-example.md). If an `AGENTS.md` already exists, paste in only the marker block (or let `owfa init` append it).
124
- 2. **Create the four directories**: `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`. Derived pages build themselves.
125
- 3. **Converge**:
130
+ 2. **Converge**:
126
131
 
127
132
  ```bash
128
- python .meta/scripts/wiki_plugin_kernel.py all
133
+ python .owfa/scripts/owfa_kernel.py all
129
134
  ```
130
135
 
131
- Expected: all core plugins validate, package rosters reconcile, the injection region is rebuilt, command copies are in sync.
136
+ Expected: the personal suite's 21 members validate, package rosters reconcile, the injection region is rebuilt, command copies are in sync. The four skeleton directories (`vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`) came with the suite install — its `PKG.yaml` `skeleton:` declares them; the channel hardcodes no instance layout.
132
137
 
133
138
  ### 4.3 "Installing the kernel"
134
139
 
135
- There is nothing separate to install. The kernel is the file `.meta/scripts/wiki_plugin_kernel.py` inside Core; Python 3.9+ runs it. Verify it:
140
+ There is nothing separate to install. The kernel is the file `.owfa/scripts/owfa_kernel.py` inside Core; Python 3.9+ runs it. Verify it:
136
141
 
137
142
  ```bash
138
- python3 .meta/scripts/wiki_plugin_kernel.py validate # structural check, read-only
139
- python3 .meta/scripts/wiki_plugin_kernel.py ls # 21 core plugins
140
- python3 .meta/scripts/wiki_plugin_kernel.py pkg # installed packages + core remainder
143
+ python3 .owfa/scripts/owfa_kernel.py validate # structural check, read-only
144
+ python3 .owfa/scripts/owfa_kernel.py ls # the personal suite's 21 members (the framework tree itself carries none)
145
+ python3 .owfa/scripts/owfa_kernel.py pkg # installed packages + the unclaimed core remainder
141
146
  ```
142
147
 
143
148
  On Windows, `python` may be `py -3`; the CLI probes `python3`, `python`, then `py -3`. Set `OWFA_PYTHON=/path/to/python3` to override. If the kernel is missing, the Core copy is incomplete — recopy the tree, do not "pip install" anything.
@@ -175,7 +180,7 @@ The daily loops — library keeping, course learning, collaborative development
175
180
 
176
181
  ## 7. Packages — finding and installing
177
182
 
178
- Core ships only the framework plugins. External systems arrive as **packages**: one directory `.meta/plugins/domains/<pkg>/` with a `PKG.yaml` roster, plugin masters, commands and connectors.
183
+ Core itself is two-stage since v0.4: the kernel payload lands first, then `init` installs the embedded **blessed suite** — the former framework plugins, now shipped as the **owfa-personal** package (a vetted copy bundled inside the tarball) — by default (`--core none` skips it, `--core <pkg>` installs a different core package). External systems arrive the same way, as **packages**: one directory `.owfa/plugins/domains/<pkg>/` with a `PKG.yaml` roster, plugin masters, commands and connectors.
179
184
 
180
185
  ### 7.1 Find what exists
181
186
 
@@ -185,28 +190,28 @@ Run these inside the instance:
185
190
  owfa list # registry catalog: versions, compat floors, installed marks
186
191
  owfa pkg # what is installed here: members, connectors, core remainder
187
192
  # the same through the kernel:
188
- python3 .meta/scripts/wiki_plugin_kernel.py list-remote
189
- python3 .meta/scripts/wiki_plugin_kernel.py pkg
193
+ python3 .owfa/scripts/owfa_kernel.py list-remote
194
+ python3 .owfa/scripts/owfa_kernel.py pkg
190
195
  ```
191
196
 
192
- The registry is the GitHub index at `owfadev/registry`; before installing, it is also readable directly as `INDEX.yaml` in that repository. Each row shows the package version, the framework compat floor, the member plugins and the trust level.
197
+ The registry is the GitHub index at `owfadev/owfa-registry`; before installing, it is also readable directly as `INDEX.yaml` in that repository. Each row shows the package version, the framework compat floor, the member plugins and the trust level.
193
198
 
194
199
  ### 7.2 Install a package
195
200
 
196
201
  ```bash
197
202
  owfa add cuhksz # wraps kernel install + convergence
198
203
  # equivalent, and more explicit:
199
- python3 .meta/scripts/wiki_plugin_kernel.py install cuhksz --yes
204
+ python3 .owfa/scripts/owfa_kernel.py install cuhksz --yes
200
205
  ```
201
206
 
202
207
  This is also what the agent's **plugin** command does: you can ask the agent to install a package by name, and it drives the same kernel. The CLI is the human/script equivalent.
203
208
 
204
- What lands: plugin masters under `.meta/plugins/domains/<pkg>/`, command masters, in-repo connectors, skill copies, injection blocks, registry rows. Then the kernel converges. If the package declares a **first-run semantic migration** (root packages such as `project` do), the install stages it and `validate` stays red until an agent performs the semantic step:
209
+ What lands: plugin masters under `.owfa/plugins/domains/<pkg>/`, command masters, in-repo connectors, skill copies, injection blocks, registry rows. Then the kernel converges. If the package declares a **first-run semantic migration** (root packages such as `project` do), the install stages it and `validate` stays red until an agent performs the semantic step:
205
210
 
206
211
  ```bash
207
- python3 .meta/scripts/wiki_plugin_kernel.py migrate <pkg>
212
+ python3 .owfa/scripts/owfa_kernel.py migrate <pkg>
208
213
  # read the printed page, create the declaration/identity page, then:
209
- python3 .meta/scripts/wiki_plugin_kernel.py migrate <pkg> --clear
214
+ python3 .owfa/scripts/owfa_kernel.py migrate <pkg> --clear
210
215
  ```
211
216
 
212
217
  The CLI stops and reports this instead of pretending convergence. `owfa add` exits non-zero in that state.
@@ -216,16 +221,16 @@ Other forms:
216
221
  - `kernel install <pkg>@<tag>` — pin a release tag;
217
222
  - `kernel install <owner>/<repo> --yes` — an unindexed repository (trust: unknown; `--yes` is the trust gate);
218
223
  - `kernel install <pkg> --path ./local-pkg` — a local package (channel C, no registry);
219
- - `--without a,b` — subset grammar is reserved; v1 reports not-yet-open. Offline alternative: copy `domains/<pkg>/` into `.meta/plugins/domains/` and rerun `all`.
224
+ - `--without a,b` — subset grammar is reserved; v1 reports not-yet-open. Offline alternative: copy `domains/<pkg>/` into `.owfa/plugins/domains/` and rerun `all`.
220
225
 
221
226
  Trust levels are visible in `owfa list`: `framework-bundled` and `reviewed-3rd-party` install without a prompt; anything else needs `--yes` and is reported as unknown.
222
227
 
223
228
  ### 7.3 Upgrade and uninstall packages
224
229
 
225
230
  ```bash
226
- python3 .meta/scripts/wiki_plugin_kernel.py upgrade # reconciliation report (read-only)
227
- python3 .meta/scripts/wiki_plugin_kernel.py upgrade <pkg> --yes # silent reinstall, per package, never cascaded
228
- python3 .meta/scripts/wiki_plugin_kernel.py uninstall <pkg> --yes
231
+ python3 .owfa/scripts/owfa_kernel.py upgrade # reconciliation report (read-only)
232
+ python3 .owfa/scripts/owfa_kernel.py upgrade <pkg> --yes # silent reinstall, per package, never cascaded
233
+ python3 .owfa/scripts/owfa_kernel.py uninstall <pkg> --yes
229
234
  ```
230
235
 
231
236
  - Package versions are release ordinals riding their own tags; member plugin versions do not lockstep.
@@ -237,30 +242,30 @@ python3 .meta/scripts/wiki_plugin_kernel.py uninstall <pkg> --yes
237
242
  ### npm channel
238
243
 
239
244
  ```bash
240
- npx owfa upgrade # replace .meta/ + .agents/skills/ with the channel's version
245
+ npx owfa upgrade # replace .owfa/ + .agents/skills/ with the channel's version
241
246
  npx owfa upgrade --check # read-only report
242
247
  npx owfa upgrade --backup # keep a copy under .owfa/backup/<version>-<timestamp>/
243
248
  ```
244
249
 
245
- `upgrade` preserves the instance-local kernel state (`.meta/migrations/pending.json`, `.meta/kernel-journal.log`, `.meta/registry-cache.yaml`), replaces local edits under the two framework trees (instance hotfixes belong in git), and reruns `all`. A pending semantic migration blocks convergence and is reported with the exact `migrate` command.
250
+ `upgrade` preserves the instance-local kernel state (`.owfa/migrations/pending.json`, `.owfa/kernel-journal.log`, `.owfa/registry-cache.yaml`), replaces local edits under the two framework trees (instance hotfixes belong in git), and reruns `all`. A pending semantic migration blocks convergence and is reported with the exact `migrate` command.
246
251
 
247
252
  ### git channel
248
253
 
249
- Re-copy `.meta/` and `.agents/skills/` from the new template revision (review the diff, do not blind-copy over pending migrations), then `kernel all`. The instance git snapshot is the rollback path.
254
+ Re-copy `.owfa/` and `.agents/skills/` from the new template revision (review the diff, do not blind-copy over pending migrations), then `kernel all`. The instance git snapshot is the rollback path.
250
255
 
251
- Framework versions are anchored by `.meta/VERSION` (0.3); a target-side semantic migration can be staged by an upgrade, with the same tri-face warning and `kernel migrate` flow.
256
+ Framework versions are anchored by `.owfa/VERSION` (0.4.0); a target-side semantic migration can be staged by an upgrade, with the same tri-face warning and `kernel migrate` flow.
252
257
 
253
258
  ## 9. Uninstall
254
259
 
255
260
  - **A package**: `kernel uninstall <pkg> --yes`; data zones stay, credentials are only reminded, never deleted.
256
- - **The whole framework**: delete `.meta/`, `.agents/skills/`, and the `AGENTS.md` injection region block. `vault/` and `wiki/` are yours; dispose of them as you see fit. Nothing else is installed.
261
+ - **The whole framework**: delete `.owfa/`, `.agents/skills/`, and the `AGENTS.md` injection region block. `vault/` and `wiki/` are yours; dispose of them as you see fit. Nothing else is installed.
257
262
 
258
263
  ## 10. Troubleshooting
259
264
 
260
265
  | Symptom | Cause / fix |
261
266
  |---|---|
262
267
  | `Python 3.9+ not found` | install Python 3, or set `OWFA_PYTHON`; the installer is Node-only, the runtime is Python |
263
- | `already contains .meta/` | it is an instance — `owfa upgrade`; `--force` re-copies the trees |
268
+ | `already contains .owfa/` | it is an instance — `owfa upgrade`; `--force` re-copies the trees |
264
269
  | `npx` runs an old version | `npx owfa@latest …`; npm caches by version range |
265
270
  | `publish` / `npx` 403 on `owfa` | the name is frozen on similarity grounds; use the `owfadev` fallback or wait for the application |
266
271
  | upgrade blocked by pending migrations | run `kernel migrate <pkg>`, perform the semantic step, then `--clear` |
@@ -276,11 +281,11 @@ Framework versions are anchored by `.meta/VERSION` (0.3); a target-side semantic
276
281
  | `vault/` | real assets | yes — the human owns it |
277
282
  | `wiki/` | markdown world, proxies, notes, sessions | yes, via commands; derived pages are rebuilt |
278
283
  | `wiki/index.md`, `tags.md`, `hot.md`, `log.md` | derived layer | no — the pipeline rewrites them |
279
- | `.meta/plugins/` | Core plugins + installed packages | no — framework authoring |
280
- | `.meta/scripts/` | kernel, pipeline, wikilib | no — framework authoring |
281
- | `.meta/command/` | command masters | no |
284
+ | `.owfa/plugins/` | Core plugins + installed packages | no — framework authoring |
285
+ | `.owfa/scripts/` | kernel, pipeline, wikilib | no — framework authoring |
286
+ | `.owfa/command/` | command masters | no |
282
287
  | `.agents/skills/` | deployed skill copies | no — `kernel deploy` syncs them |
283
- | `.meta/migrations/` | staged semantic migrations + ledger | no — kernel zone |
288
+ | `.owfa/migrations/` | staged semantic migrations + ledger | no — kernel zone |
284
289
  | `projects/` | project containers (if the project package is installed) | yes — project-owned |
285
290
 
286
291
  ## 12. FAQ
@@ -7,8 +7,8 @@
7
7
  | Your plugin is… | It lands… | Trust gate |
8
8
  |---|---|---|
9
9
  | a **domain member** (depends chain reaches a domain root, e.g. bb-family) | that domain package's repo — PR there. Not a choice: the family closure claims it mechanically (`PKG.members` must include you or validate errors) | package maintainers |
10
- | a **new domain** of its own | your own repo as a package (`PKG.yaml`, see [packages.md](packages.md)) + a one-line PR to the [registry](https://github.com/owfadev/registry) | the registry PR — the human-review gate (inject text and connectors are the security faces, #12) |
11
- | **cross-cutting / non-domain** (global piece) | the framework repo's `core/` — PR there | owner review (charter-level, highest bar) |
10
+ | a **new domain** of its own | your own repo as a package (`PKG.yaml`, see [packages.md](packages.md)) + a one-line PR to the [registry](https://github.com/owfadev/owfa-registry) | the registry PR — the human-review gate (inject text and connectors are the security faces, #12) |
11
+ | **cross-cutting / non-domain** (global piece) | the core suite package repo (**owfa-personal**, since the v0.4 split) — PR there | owner review (charter-level, highest bar) |
12
12
 
13
13
  A single plugin never ships bare — the package is the distribution unit. A lone plugin is a single-member package (12 lines of PKG.yaml, see email/bili/project). Users prune with `--without` (subset grammar), so contributing into a big package never forces users to install all of it.
14
14
 
@@ -19,8 +19,8 @@ A single plugin never ships bare — the package is the distribution unit. A lon
19
19
  3. **Integration-test without a monorepo**: in the sandbox (or any instance),
20
20
  ```
21
21
  cd test-repo
22
- python .meta/scripts/wiki_plugin_kernel.py install <pkg> --path /path/to/your/clone
23
- python .meta/scripts/wiki_plugin_kernel.py validate --scope <pkg>
22
+ python .owfa/scripts/owfa_kernel.py install <pkg> --path /path/to/your/clone
23
+ python .owfa/scripts/owfa_kernel.py validate --scope <pkg>
24
24
  ```
25
25
  `--path` installs the local clone (channel C); iterate freely — reinstall after uninstalling, or just re-copy
26
26
  4. **PR** — one thing per commit, `模块: 概述`; self-check per [CONTRIBUTING](../../CONTRIBUTING.md) (framework root: `validate`; sandbox: `all`)
@@ -22,14 +22,15 @@ The npm tarball is the framework body, byte-for-byte what the git channel copies
22
22
 
23
23
  | Path | Contents | In tarball |
24
24
  |---|---|---|
25
- | `.meta/` | kernel, plugins, commands, protocol, docs | yes |
26
- | `.agents/skills/` | command/connector skill copies | yes |
25
+ | `.owfa/` | kernel, framework commands, protocol, docs — no plugins (the v0.4 split) | yes |
26
+ | `.agents/skills/` | framework command/connector skill copies | yes |
27
+ | `payloads/personal/` | the embedded **blessed suite** — the owfa-personal package (21 plugin masters + its command masters) that a default init installs offline | yes |
27
28
  | `templates/AGENTS.template.md` | the instance shell with the injection markers | yes |
28
29
  | `bin/owfa.js` | CLI (zero dependencies) | yes |
29
30
  | `README.md`, `LICENSE` | — | yes |
30
31
  | `test/`, `scripts/`, `CONTRIBUTING.md`, `.github/` | development-only | no |
31
32
 
32
- Local state never ships: `__pycache__`, `*.pyc`, `.meta/kernel-journal.log`, `.meta/migrations/pending.json`, `.meta/registry-cache.yaml`, `test-repo/`. The release gate (`scripts/verify-release.js`) refuses to publish if any of them would be packed.
33
+ Local state never ships: `__pycache__`, `*.pyc`, `.owfa/kernel-journal.log`, `.owfa/migrations/pending.json`, `.owfa/registry-cache.yaml`, `test-repo/`. The release gate (`scripts/verify-release.js`) refuses to publish if any of them would be packed.
33
34
 
34
35
  ## Commands
35
36
 
@@ -43,13 +44,13 @@ owfa pkg
43
44
  owfa version
44
45
  ```
45
46
 
46
- **init** — additive deployment, the five manual steps in [deployment.md](deployment.md) mechanized:
47
+ **init** — additive deployment, the manual steps in [deployment.md](deployment.md) mechanized, two-stage by default:
47
48
 
48
- 1. copies `.meta/` and `.agents/skills/` from the tarball
49
- 2. creates `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`
50
- 3. writes `AGENTS.md` from the template when absent; when one exists, **appends only the injection region** (handwritten content before it is preserved byte-for-byte); refuses if the markers are half-present
51
- 4. runs `python .meta/scripts/wiki_plugin_kernel.py all` (validate, inject, registry, skills)
52
- 5. optionally installs packages from the registry (`--packages cuhksz,lark`)
49
+ 1. copies `.owfa/` and `.agents/skills/` from the tarball
50
+ 2. writes `AGENTS.md` from the template when absent; when one exists, **appends only the injection region** (handwritten content before it is preserved byte-for-byte); refuses if the markers are half-present
51
+ 3. runs `python .owfa/scripts/owfa_kernel.py all` (validate → inject → registry → deploy) over the kernel-only tree
52
+ 4. installs the embedded personal suite offline (`payloads/personal/`) — its `skeleton:` declaration creates `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`; `--core none` skips this stage, `--core <pkg-id>` takes the suite from the registry
53
+ 5. optionally installs further packages from the registry (`--packages cuhksz,lark`)
53
54
 
54
55
  A package may declare a **first-run semantic migration** (root packages such as `project` do). Installing it stages the migration, and the CLI stops there with the exact `kernel migrate` command — clearing it is an agent act (create the identity/declaration page), not something a mechanical installer may fake. `init --packages` therefore exits non-zero in that state: the workspace is installed but not converged.
55
56
 
@@ -57,9 +58,10 @@ A package may declare a **first-run semantic migration** (root packages such as
57
58
 
58
59
  **upgrade** — tree replacement plus convergence:
59
60
 
60
- - compares the instance's `.meta/VERSION` with the tarball's; refuses downgrades unless `--force`
61
- - preserves instance-local kernel state: `.meta/migrations/pending.json`, `.meta/kernel-journal.log`, `.meta/registry-cache.yaml`
62
- - **replaces** local edits under `.meta/` and `.agents/skills/` — instance hotfixes belong in the instance's git history, which is the rollback path (the `--backup` flag also drops a copy under `.owfa/backup/<version>-<timestamp>/`)
61
+ - compares the instance's `.owfa/VERSION` with the tarball's; refuses downgrades unless `--force`
62
+ - preserves instance-local kernel state: `.owfa/migrations/pending.json`, `.owfa/kernel-journal.log`, `.owfa/registry-cache.yaml`
63
+ - **replaces** local edits under `.owfa/` and `.agents/skills/` — instance hotfixes belong in the instance's git history, which is the rollback path (the `--backup` flag also drops a copy under `.owfa/backup/<version>-<timestamp>/`)
64
+ - **converts** an in-tree core (every 0.3 / compat-era instance) into the personal suite package on the way in — the parked masters are rescued from the attic and adopted mechanically (`kernel upgrade personal` later swaps in the canonical suite)
63
65
  - reruns `all`; a pending semantic migration blocks convergence and is reported with the exact `kernel migrate` command
64
66
  - `--check` is a read-only report
65
67
 
@@ -67,13 +69,13 @@ A package may declare a **first-run semantic migration** (root packages such as
67
69
 
68
70
  **add** — thin wrapper over `kernel install` plus convergence. Registry trust rules still apply; `--yes` is forwarded. A staged first-run migration stops the command with the exact `migrate` hint (exit non-zero) instead of a false "done".
69
71
 
70
- **list** — `kernel list-remote`: the registry catalog with package versions, framework compat floors, member plugins, trust levels and installed marks. **pkg** — `kernel pkg`: what is installed in this instance (packages, members, connectors, core remainder).
72
+ **list** — `kernel list-remote`: the registry catalog with package versions, framework compat floors, member plugins, trust levels and installed marks. **pkg** — `kernel pkg`: what is installed in this instance (packages, members, connectors, and plugins unclaimed by any package).
71
73
 
72
74
  ## Version invariant
73
75
 
74
- The npm version rides the framework anchor: `.meta/VERSION` `0.3` → package `0.3.x`. The release gate refuses a package whose `major.minor` diverges, and refuses a `v*` tag that does not match the package version exactly. `.meta/VERSION` still tracks the kernel contract, not product maturity (stage labels live in the README); npm patch releases may fix packaging without touching the contract.
76
+ The version equation is exact equality across five carriers: `.owfa/VERSION` == `package.json` == git tag `vA.B.C` == the published npm version == the GitHub Release. `.owfa/VERSION` carries the **full release number** (`A.B.C`, e.g. `0.4.0`) — not a two-segment anchor riding the package's `major.minor`. The release gate (`scripts/verify-release.js`) refuses any drift: a tag that does not match the package version exactly, a `.owfa/VERSION` that diverges from either, or a publish that would break the equation all fail closed. A patch release therefore bumps all five carriers together in one commit. `.owfa/VERSION` still tracks the kernel contract, not product maturity (stage labels live in the README).
75
77
 
76
- Install identification is therefore trivial: `.meta/VERSION` says which framework a workspace is on; `owfa version` says which channel the CLI is on.
78
+ Install identification is therefore trivial: `.owfa/VERSION` says which framework a workspace is on; `owfa version` says which channel the CLI is on.
77
79
 
78
80
  ## Release runbook
79
81
 
@@ -88,8 +90,8 @@ Every release:
88
90
 
89
91
  ```bash
90
92
  # 1. the framework contract and the package version move together
91
- $EDITOR .meta/VERSION # e.g. 0.3 -> 0.4
92
- $EDITOR package.json # "version": "0.4.0"
93
+ $EDITOR .owfa/VERSION # full A.B.C, e.g. 0.3.0 -> 0.4.0 — VERSION carries the full release number
94
+ $EDITOR package.json # "version": "0.4.0" — must equal .owfa/VERSION exactly
93
95
  git commit -am "release: framework 0.4.0"
94
96
  git tag v0.4.0 && git push --follow-tags
95
97
  ```
@@ -125,8 +127,8 @@ npm pack --dry-run
125
127
  | Symptom | Cause / fix |
126
128
  |---|---|
127
129
  | `Python 3.9+ not found` | install Python 3, or set `OWFA_PYTHON=/path/to/python3`; the installer itself is Node-only |
128
- | `already contains .meta/` | the directory is already an instance — use `owfa upgrade`; `--force` re-copies the trees |
130
+ | `already contains .owfa/` | the directory is already an instance — use `owfa upgrade`; `--force` re-copies the trees |
129
131
  | `npx` runs an old version | `npx owfa@latest …`; npm caches by version range |
130
- | upgrade blocked by pending migrations | run `python .meta/scripts/wiki_plugin_kernel.py migrate <pkg>` and follow the printed page before upgrading again |
132
+ | upgrade blocked by pending migrations | run `python .owfa/scripts/owfa_kernel.py migrate <pkg>` and follow the printed page before upgrading again |
131
133
  | publish fails: name too similar | npm froze `owfa` (similar to `ow`/`ora`); use the `owfadev` fallback or wait for the application; do not retry the same name |
132
134
  | Windows: `python` opens the Store | install Python 3 and ensure `py -3` or `python3` works; `OWFA_PYTHON` overrides detection |
@@ -0,0 +1,61 @@
1
+ # Machine substrate: `~/.owfa` — connector homes and workspace bindings
2
+
3
+ > v0.4 work order #56 (B1-B3). One machine hosts many OWFA workspaces; connector
4
+ > state must not collide across them. This is the shared contract every OWFA
5
+ > connector inherits by importing `.owfa/scripts/owfa_home.py` — no connector
6
+ > invents its own layout.
7
+
8
+ ## Layout
9
+
10
+ ```
11
+ ~/.owfa/ # machine substrate (env: OWFA_HOME)
12
+ └── connectors/<name>/
13
+ ├── bindings.json # registry: [{id, root, home, bot?, installed_at}]
14
+ └── homes/<id>/ # one state dir per binding — credentials,
15
+ # spool, logs; 0600/0700, never in any repo
16
+ ```
17
+
18
+ - `<id>` = human alias + 2-byte hash (`repo-a1b2`); the singleton case is
19
+ literally `default`.
20
+ - Homes are **machine-global, not per-instance**: a connector does not read the
21
+ workspace; only its binding records which workspace drains it.
22
+
23
+ ## Resolution order
24
+
25
+ `--root/--home` argument → `OWFA_ROOT` env → cwd reverse-lookup in the registry
26
+ → `homes/default` (single-workspace machines: zero configuration).
27
+
28
+ On a machine with **two or more bindings**, a workspace matching none of them
29
+ still falls through to `homes/default` (degraded-but-healthy) but emits a loud
30
+ stderr warning: default is unregistered there, and two unmatched workspaces
31
+ sharing it would be invisible to `exclusivity_violations`. Remove the ambiguity
32
+ by binding the root explicitly or setting `OWFA_ROOT`.
33
+
34
+ ## Invariants
35
+
36
+ 1. **One home, one active binding.** Two workspaces draining one spool is a
37
+ semantic error (`exclusivity_violations` → error, the only error-level health
38
+ state in the substrate).
39
+ 2. **Unbound workspace = degraded-but-healthy** (warning in domain checks): the
40
+ domain is installed, the skill answers with guidance, nothing drains.
41
+ 3. **Unbind detaches, never deletes.** `homes/<id>/` holds credentials and
42
+ spool data — deletion is a human act, confirmed.
43
+ 4. **Stale bindings** (workspace root gone) are reported and cleaned on
44
+ confirmation — same rhythm as the tmp zone's stale_after.
45
+
46
+ ## Migration from pre-0.4 scattered homes
47
+
48
+ `owfa_home.migrate_legacy_home("qq-cli", "~/.qq-cli")` **moves** the legacy
49
+ directory into `homes/<id>` (move, never copy — credentials must not exist in
50
+ two places) and leaves a symlink at the old path so old absolute references keep
51
+ resolving; the symlink is the 0.5-cleanup item. Version-gated per connector: a
52
+ connector that finds its legacy home on first run offers the migration instead
53
+ of silently creating a second home.
54
+
55
+ ## Harness scope
56
+
57
+ Connector manifests (PKG.yaml `connectors[]`) may declare `home:` for external
58
+ connectors whose state lives outside this substrate (declared, not migrated).
59
+ The registry mirrors per-package `harness:` — `universal` connectors are the
60
+ first class; harness-locked ones register honestly and health checks surface the
61
+ mismatch.
@@ -47,10 +47,10 @@ A minimal chronology: 2026-08 the personal vault founded; 09-08 the prototype la
47
47
  |---|---|
48
48
  | Constitution and collaboration red lines | `AGENTS.md` |
49
49
  | Mechanics overview | the kernel reference skill |
50
- | How the mechanics work | `.meta/docs/mechanics.md` |
51
- | Daily usage | `.meta/docs/usage.md` |
52
- | Using the sandbox | `.meta/docs/sandbox.md` |
50
+ | How the mechanics work | `.owfa/docs/mechanics.md` |
51
+ | Daily usage | `.owfa/docs/usage.md` |
52
+ | Using the sandbox | `.owfa/docs/sandbox.md` |
53
53
  | Why a plugin is designed this way | that plugin's `PLUGIN.md` |
54
- | Research basis | `.meta/docs/research-*.md` |
55
- | Deployment guide | `.meta/docs/deployment.md` (five-minute path: `.meta/docs/quickstart.md`) |
54
+ | Research basis | `.owfa/docs/research-*.md` |
55
+ | Deployment guide | `.owfa/docs/deployment.md` (five-minute path: `.owfa/docs/quickstart.md`) |
56
56
  | Run history and current state | `log.md` |
@@ -5,7 +5,7 @@
5
5
  ```markdown
6
6
  # 运行日志
7
7
 
8
- > 置顶追加、只增不删;条目 = `- YYYY-MM-DD <类型> [<域>]:一句话`(域标可缺省——无域事务,log 桥)。规则见 `.meta/plugins/core/log/`,写走 `pipeline.py log`。
8
+ > 置顶追加、只增不删;条目 = `- YYYY-MM-DD <类型> [<域>]:一句话`(域标可缺省——无域事务,log 桥)。规则见 personal 套件(owfa-personal,内嵌副本 `payloads/personal/log/`)的 log 插件,写走 `pipeline.py log`。
9
9
 
10
10
  - 2026-10-12 other:<one sentence: what happened, from which domain, with what outcome>
11
11
  - 2026-10-12 map:<one sentence per mapping transaction>
@@ -1,6 +1,6 @@
1
1
  # Docs map — what to read when
2
2
 
3
- > The routing table for `.meta/docs/` (framework) and package-repo docs. The entry index for agents; skills point here, the documents stay the source of truth.
3
+ > The routing table for `.owfa/docs/` (framework) and package-repo docs. The entry index for agents; skills point here, the documents stay the source of truth.
4
4
 
5
5
  | Situation | Read |
6
6
  |---|---|
@@ -12,12 +12,13 @@
12
12
  | Installing/upgrading the framework body; npm channel; release runbook | [distribution.md](distribution.md) |
13
13
  | The name: OWFA expansion, two names two jobs, collision policy | [naming.md](naming.md) |
14
14
  | Converting a legacy (pre-split flat) instance to the package era | [conversion.md](conversion.md) — the eight-step drill walked on a real instance |
15
- | Instance git usage (snapshots, red lines, recovery) | the [instance-git plugin](../plugins/core/instance-git/PLUGIN.md) (core 21) |
15
+ | Instance git usage (snapshots, red lines, recovery) | the instance-git plugin (personal suite member; canonical repo [owfa-personal](https://github.com/owfadev/owfa-personal), embedded copy at `payloads/personal/instance-git/`) |
16
16
  | Framework mechanics: projections, bridges, injection, inject tiers | [mechanics.md](mechanics.md) |
17
17
  | (Un)install history, package lifecycle | [mechanics.md](mechanics.md) §7 + [packages.md](packages.md) |
18
+ | Third-party view: develop → publish → install → update → uninstall; name governance | [plugin-lifecycle.md](plugin-lifecycle.md) |
18
19
  | Experiments: sandbox or local | [sandbox.md](sandbox.md) |
19
20
  | Development rules, commit flow, template + instance workflow | [CONTRIBUTING.md](../../CONTRIBUTING.md) — template-repo root (an instance reads it there, never keeps a copy) |
20
21
  | Day-to-day usage loops | [usage.md](usage.md) |
21
22
  | What the framework is, intro | [intro.md](intro.md) |
22
- | Package-side plugin docs (bb family, lark family, …) | the owning `pkg-*` repo's plugin masters |
23
+ | Package-side plugin docs (bb family, lark family, …) | the owning `owfa-*` repo's plugin masters |
23
24
  | AGENTS.md seed / log seed examples | [agents-example.md](agents-example.md), [log-example.md](log-example.md) |
@@ -1,17 +1,17 @@
1
1
  # Mechanics in Detail
2
2
 
3
- > Audience: members and contributors who will modify the framework. The authoritative source of mechanical rules is the kernel reference skill and the `.meta/` source code. This document expands the master outline by one level — principles, instance walkthroughs, and hands-on procedures — without copying rule text; where it conflicts with the source, the source prevails. Written 2026-10-04.
3
+ > Audience: members and contributors who will modify the framework. The authoritative source of mechanical rules is the kernel reference skill and the `.owfa/` source code. This document expands the master outline by one level — principles, instance walkthroughs, and hands-on procedures — without copying rule text; where it conflicts with the source, the source prevails. Written 2026-10-04.
4
4
 
5
5
  ## 0. One Source, Five Projections
6
6
 
7
- Each plugin is one directory, living at `.meta/plugins/<id>/`. `PLUGIN.yaml` is the machine-readable body — the manifest. From the manifest, the kernel script mechanically projects into five places:
7
+ Each plugin is one directory, living at `.owfa/plugins/<id>/`. `PLUGIN.yaml` is the machine-readable body — the manifest. From the manifest, the kernel script mechanically projects into five places:
8
8
 
9
9
  | Projection | Landing point | Source key | Who reads it |
10
10
  |---|---|---|---|
11
11
  | AGENTS injection region | `<!-- plugin:<id> v<x> -->` marker block | `inject` | The agent of every session; constitution-level disclosure |
12
12
  | check inspection block | the `check-inject` block inside the check command | `checks` | The check command; semantic items |
13
13
  | command usage block | the `cmd-inject` block inside each command | `usage`, in consumes order | Command execution sites; write-side rules |
14
- | registry plugin section | `.meta/protocol/registry.yaml` | `fields` | Commands consulting the field vocabulary before writing pages |
14
+ | registry plugin section | `.owfa/protocol/registry.yaml` | `fields` | Commands consulting the field vocabulary before writing pages |
15
15
  | skill copy | `.agents/skills/<command>/` | command and connector masters | Deployment-side agents |
16
16
 
17
17
  The key property is idempotent rebuilding. Hand-editing inside marker blocks is forbidden — a rebuild overwrites; prose outside the blocks belongs to humans. There is no second source of truth: changing a rule means changing the manifest, after which the single command `all` converges everything. The whole class of documentation-drift problems is eliminated wholesale — projections and the body cannot disagree, because they are not two separate things.
@@ -38,7 +38,7 @@ Seven required manifest keys, illustrated with real values from bb-quiz v0.2:
38
38
 
39
39
  Four optional keys. `commands` declares the commands this plugin drives; `usage` is the write-side rule list; `checks` is the inspection rules; `bridge` is the bridge declaration, which only global pieces may hold.
40
40
 
41
- A fifth optional key `inject_tier` (full|member, default full) carries the **tier law** (issue #12 layer discipline): member exits the AGENTS injection region — exposure rides on the family root's roster line, the skill catalog, and on-demand reads of the manifest, and validate requires a member to reach a full-tier domain root through depends. The projected region carries a byte budget (15 KiB), keeping the A layer pointer-dense: pointers and red lines, never procedures or formats (contract in `protocol/experiments.md`).
41
+ A fifth optional key `inject_tier` (full|member, default full) carries the **tier law** (issue #12 layer discipline): member exits the AGENTS injection region — exposure rides on the family root's roster line, the skill catalog, and on-demand reads of the manifest, and validate requires a member to reach a full-tier domain root through depends. The projected region carries a byte budget (16 KiB), keeping the A layer pointer-dense: pointers and red lines, never procedures or formats (contract in `protocol/experiments.md`). Each full-tier inject line also has a 256 B pointer-density guideline (issue #49) — over it, validate warns: keep the line to path + read/write trigger + the one easy-to-break invariant + a pointer to PLUGIN.md.
42
42
 
43
43
  attachment deserves a closer look. bb-quiz declares three entries:
44
44
 
@@ -52,7 +52,7 @@ The first is ownership; the latter two are borrows: the territory belongs to ano
52
52
 
53
53
  `depends` declares dependencies. validate checks two things: dependencies exist, and there are no cycles — cycles are detected via DFS.
54
54
 
55
- A domain piece is any plugin whose depends chain reaches `domain`. Those connecting to domain directly are domain bases — the five pieces vault, lark, project, email, bb; pieces inside a domain belong to it transitively, without connecting directly. bb-quiz does not connect to domain directly: it arrives via `bb-quiz → bb-track → bb-map → bb → domain`, and is thus a domain piece.
55
+ A domain piece is any plugin whose depends chain reaches `domain`. Those connecting to domain directly are domain bases — the six pieces vault, lark, project, email, bb, bili; pieces inside a domain belong to it transitively, without connecting directly. bb-quiz does not connect to domain directly: it arrives via `bb-quiz → bb-track → bb-map → bb → domain`, and is thus a domain piece.
56
56
 
57
57
  Injection order = dependency topology plus alphabetical order within a batch: dependees are injected first; same-batch pieces sort by name. Look at the bb family's depends and the real order in the injection region:
58
58
 
@@ -69,8 +69,8 @@ This guarantees one thing: when a consumer-side plugin is injected, the disclosu
69
69
 
70
70
  Suppose you want to add one discipline to bb-quiz's write-side rules — here is what happens:
71
71
 
72
- 1. Edit the `usage:` list in `.meta/plugins/bb-quiz/PLUGIN.yaml` and add a line. While at it, bump `version` and refresh `updated`; add a line to PLUGIN.md's Changelog
73
- 2. Run `python .meta/scripts/wiki_plugin_kernel.py all`. In sequence: validate goes first — failure blocks, fix and rerun; if the inject line changed too, the AGENTS injection region is rebuilt; the cmd-inject blocks of the two command SKILL masters bb-quiz and bb-track are rebuilt — the usage appears in every command whose consumes includes bb-quiz; the registry plugin section is rebuilt; skill copies are synced
72
+ 1. Edit the `usage:` list in `.owfa/plugins/bb-quiz/PLUGIN.yaml` and add a line. While at it, bump `version` and refresh `updated`; add a line to PLUGIN.md's Changelog
73
+ 2. Run `python .owfa/scripts/owfa_kernel.py all`. In sequence: validate goes first — failure blocks, fix and rerun; if the inject line changed too, the AGENTS injection region is rebuilt; the cmd-inject blocks of the two command SKILL masters bb-quiz and bb-track are rebuilt — the usage appears in every command whose consumes includes bb-quiz; the registry plugin section is rebuilt; skill copies are synced
74
74
  3. Self-review the diff. Changes should land only in the manifest, the two command SKILL masters, and the `.agents/skills/` copies; if inject or fields changed, AGENTS and registry change as well. Any change beyond these is an anomaly
75
75
  4. Commit in the format `plugin: bb-quiz …`; one commit does one thing
76
76
 
@@ -105,7 +105,7 @@ Division of labor: the bridge holds validation and declaration — who may attac
105
105
 
106
106
  ## 6. The Derived Layer
107
107
 
108
- The kernel governs the framework area — plugins and projections; pipeline governs the data area — wiki derived pages. The commands are `python .meta/scripts/pipeline.py index / tags / hot / log / verify`:
108
+ The kernel governs the mechanisms and projections — the plugin graph, manifest compliance, and everything derived from them (since the v0.4 split, plugin *content* travels with packages; the kernel's authority over it is mechanical, not editorial); pipeline governs the data area — wiki derived pages. The commands are `python .owfa/scripts/pipeline.py index / tags / hot / log / verify`:
109
109
 
110
110
  - **index / tags**: directory indexes and the tag reverse index. Pure-function rebuilds that only aggregate, never inventing structure; when an index list overflows the window, split the subdirectory into its own index — the cure is more subdirectories, not editing the index
111
111
  - **hot**: the recent-change hot cache. At most 25 entries, within 5 days, each entry under 200 characters; agents read it first on entering the vault
@@ -116,9 +116,9 @@ Derived pages and projections are two applications of one philosophy: projection
116
116
 
117
117
  ## 7. (Un)install Lifecycle
118
118
 
119
- The semantic flow of (un)installing goes through the plugin command, where the agent does the semantic part; the mechanical steps are this CLI. Since the split (2026-10-12) **packages are the install unit and this lifecycle is kernel-driven** — the authoritative accounts live in [packages.md](packages.md) (package model, the migrations algebra, the uninstall contract) and in `.meta/command/plugin/SKILL.md` (the wizard protocol). What follows is the historical per-plugin flow, retained for the record; the install steps still describe authoring a new plugin inside the framework repo.
119
+ The semantic flow of (un)installing goes through the plugin command, where the agent does the semantic part; the mechanical steps are this CLI. Since the split (2026-10-12) **packages are the install unit and this lifecycle is kernel-driven** — the authoritative accounts live in [packages.md](packages.md) (package model, the migrations algebra, the uninstall contract) and in `.owfa/command/plugin/SKILL.md` (the wizard protocol). What follows is the historical per-plugin flow, retained for the record; the install steps still describe authoring a new plugin inside the framework repo.
120
120
 
121
- Install, five steps: prepare the three pieces under `.meta/plugins/<id>/`; `validate` — errors block; `all` — projections arrive; smoke test — `audit <id>`, plus a walk-through of the key flows per PLUGIN.md; log a plugin line.
121
+ Install, five steps: prepare the three pieces under `.owfa/plugins/<id>/`; `validate` — errors block; `all` — projections arrive; smoke test — `audit <id>`, plus a walk-through of the key flows per PLUGIN.md; log a plugin line.
122
122
 
123
123
  Upgrade, three steps: edit the plugin, bump `version`, add a Changelog line; `all`; log line. Package-level upgrades (`kernel upgrade`) additionally stage semantic migrations — see packages.md.
124
124
 
@@ -165,7 +165,7 @@ A two-way split inside the domain. Process products live in the domain workspace
165
165
 
166
166
  ### Connectors
167
167
 
168
- Connectors live in `connectors/` — the domain's deployment-side CLI de-facto interface plus usage disclosure: `connectors/<name>/SKILL.md` lands as the `.agents/skills/` copy via kernel `deploy`. The difference from commands: commands are pure wiki operations, masters in `.meta/command/`; connectors are data-fetching channels to external systems — credentials stay on the local machine, never committed, never persisted to disk. Domain plugins declare territory and discipline; connectors provide the de-facto interface. Discipline and tooling are separate.
168
+ Connectors live in `connectors/` — the domain's deployment-side CLI de-facto interface plus usage disclosure: `connectors/<name>/SKILL.md` lands as the `.agents/skills/` copy via kernel `deploy`. The difference from commands: commands are pure wiki operations, masters in `.owfa/command/`; connectors are data-fetching channels to external systems — credentials stay on the local machine, never committed, never persisted to disk. Domain plugins declare territory and discipline; connectors provide the de-facto interface. Discipline and tooling are separate.
169
169
 
170
170
  ## 9. Scenario Quick Reference
171
171
 
@@ -11,7 +11,7 @@ Use the expansion exactly as written. Do not expand it as *One Wiki For All* or
11
11
 
12
12
  - 中文:**一个工作区,装下你所有的 agent。**
13
13
  - 一句话:OWFA gives every agent you use one workspace to re-enter — your assets, your wiki, your instructions — instead of re-introducing yourself every session.
14
- - Agent-facing: "This is an OWFA workspace: `vault/` holds real assets, `wiki/` holds the md world, `.meta/` + `.agents/skills/` are the framework body. Read AGENTS.md, then work from the indexes."
14
+ - Agent-facing: "This is an OWFA workspace: `vault/` holds real assets, `wiki/` holds the md world, `.owfa/` + `.agents/skills/` are the framework body. Read AGENTS.md, then work from the indexes."
15
15
 
16
16
  ## What each word commits to
17
17
 
@@ -28,11 +28,11 @@ The name answers the project's actual starting pain: an agent that must be re-in
28
28
  | Layer | Name | Lives in | Job |
29
29
  |---|---|---|---|
30
30
  | Product | **OWFA** | README, npm page, docs | the brand |
31
- | Framework | **OWFA Core** (proposed) | `.meta/` + `.agents/skills/` | the body that is installed into a workspace |
31
+ | Framework | **OWFA Core** (proposed) | `.owfa/` + `.agents/skills/` | the body that is installed into a workspace |
32
32
  | Installer | **OWFA CLI** | `bin/owfa.js` (npm package) | fetch the tree, `init`, `upgrade`, `doctor`, `add` |
33
- | Engine | **kernel** | `.meta/scripts/wiki_plugin_kernel.py` | validate / inject / registry / deploy / install mechanics |
34
- | Plugin tier | **core** | `.meta/plugins/core/` | the 21 framework plugins |
35
- | Extension | **package** | `.meta/plugins/domains/<pkg>/` | domain families (cuhksz, lark, email, bili, project…) |
33
+ | Engine | **kernel** | `.owfa/scripts/owfa_kernel.py` | validate / inject / registry / deploy / install mechanics |
34
+ | Plugin tier | **core** | the owfa-personal suite package (embedded at `payloads/personal/` in the channel) | the 21 former framework plugins |
35
+ | Extension | **package** | `.owfa/plugins/domains/<pkg>/` | domain families (cuhksz, lark, email, bili, project…) |
36
36
  | Unit | **instance** | the user's directory | a deployed workspace |
37
37
 
38
38
  The call chain is the reason the names must stay distinct:
@@ -107,7 +107,7 @@ The order is not bureaucratic: npm support evaluates a project by its public hom
107
107
  - `package.json` — `"name": "owfa"` (target) with `"bin": { "owfa": "bin/owfa.js" }`; the fallback is the same file with `"name": "owfadev"` and bins `owfa` + `owfadev`
108
108
  - `README.md` — first line, the *Name* section, and the install note (never announce a command the registry does not serve)
109
109
  - `templates/AGENTS.template.md` — the identity paragraph a new instance starts from
110
- - `.meta/docs/distribution.md` — the channel's version invariant, fallback and release runbook
111
- - `scripts/verify-release.js` — the release gate (name/bin agreement, version rides `.meta/VERSION`, tag matches)
110
+ - `.owfa/docs/distribution.md` — the channel's version invariant, fallback and release runbook
111
+ - `scripts/verify-release.js` — the release gate (name/bin agreement, version rides `.owfa/VERSION`, tag matches)
112
112
 
113
113
  Update 2026-10-26: the repository itself is renamed to `owfa` (`owfadev/owfa`), and the public copy uses OWFA / OWFA Core; `vault-wiki` survives only in history and old links. Nothing in the kernel, plugin IDs, or registry depends on the brand.