opencode-wiki-historian 0.6.2 → 0.7.0

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 (56) hide show
  1. package/README.en.md +156 -42
  2. package/README.md +127 -360
  3. package/dist/anchor.js +4 -4
  4. package/dist/config.d.ts +8 -4
  5. package/dist/config.js +12 -13
  6. package/dist/index.d.ts +14 -4
  7. package/dist/index.js +21 -52
  8. package/dist/lint.d.ts +2 -2
  9. package/dist/lint.js +2 -2
  10. package/dist/maintain.d.ts +2 -2
  11. package/dist/maintain.js +7 -7
  12. package/dist/map.d.ts +1 -1
  13. package/dist/map.js +1 -1
  14. package/dist/migrate-apply.d.ts +1 -1
  15. package/dist/migrate-apply.js +1 -1
  16. package/dist/migrate-score.d.ts +2 -2
  17. package/dist/migrate-score.js +3 -3
  18. package/dist/migrate-store.d.ts +1 -1
  19. package/dist/migrate-store.js +1 -1
  20. package/dist/migrate.d.ts +2 -2
  21. package/dist/migrate.js +2 -2
  22. package/dist/prompts.d.ts +20 -0
  23. package/dist/prompts.js +46 -0
  24. package/dist/skills.d.ts +33 -0
  25. package/dist/skills.js +88 -0
  26. package/dist/surface.d.ts +1 -1
  27. package/dist/surface.js +2 -2
  28. package/dist/templates/evidence.d.ts +1 -1
  29. package/dist/templates/evidence.js +1 -1
  30. package/dist/templates/genres.d.ts +5 -5
  31. package/dist/templates/genres.js +7 -7
  32. package/dist/templates/skeletons.d.ts +3 -3
  33. package/dist/templates/skeletons.js +3 -3
  34. package/dist/tools/anchor.js +2 -2
  35. package/dist/tools/create.js +1 -1
  36. package/dist/tools/local.js +1 -1
  37. package/dist/tools/mutate.d.ts +1 -1
  38. package/dist/tools/mutate.js +1 -1
  39. package/dist/tools/shared.d.ts +3 -3
  40. package/dist/tools/shared.js +10 -10
  41. package/dist/tools.d.ts +2 -2
  42. package/dist/tools.js +2 -2
  43. package/dist/translate.d.ts +1 -1
  44. package/dist/translate.js +14 -3
  45. package/dist/v2.d.ts +114 -0
  46. package/dist/v2.js +249 -0
  47. package/dist/wiki/assets.d.ts +1 -1
  48. package/dist/wiki/assets.js +1 -1
  49. package/dist/wiki/client.d.ts +2 -3
  50. package/dist/wiki/client.js +2 -3
  51. package/dist/wiki/locale.d.ts +1 -1
  52. package/dist/wiki/locale.js +3 -3
  53. package/dist/wiki/pages.read.d.ts +1 -1
  54. package/dist/wiki/pages.write.d.ts +1 -1
  55. package/package.json +1 -1
  56. package/skills/historian/SKILL.md +2 -2
package/README.en.md CHANGED
@@ -1,46 +1,160 @@
1
1
  # opencode-historian (English)
2
2
 
3
- > Bilingual wiki curator as an OpenCode plugin. 中文文档见 [README.md](README.md).
3
+ > 中文文档见 [README.md](README.md) — this is the English front page.
4
+
5
+ > A bilingual wiki.js curator as an OpenCode plugin.
4
6
 
5
7
  ## What it is
6
- A plugin that gives an OpenCode agent a curated memory layer on top of a Wiki.js
7
- instance: bilingual (en/zh) twin pages, genre skeletons (G1–G6), full-text
8
- search, page map/timeline/maintenance sweeps, migration tooling, and a capture
9
- loop. All mutations go through read-modify-write; evidence-tier pages
10
- (`_meta/`, `_evidence/`) are machine-owned and hidden from anonymous readers.
11
-
12
- ## Tools (11)
13
- `historian_page_create / update / append / read / search / delete / move`,
14
- `historian_map` (show/refresh/timeline/maintain), `historian_migrate`,
15
- `historian_translate_snippet`, and `historian_anchor` (seal/verify human
16
- orders against the engine session store — receipts land under
17
- `_evidence/anchors/`, g12b-3).
18
-
19
- ## Configuration (plugin options in opencode.jsonc)
20
- | option | type | default | notes |
21
- |---|---|---|---|
22
- | `baseUrl` | string | `http://localhost:3000` | wiki.js root |
23
- | `apiKeyPath` | string | `~/.wikijs-api-key` | token file path |
24
- | `translate.endpoint` | string | unset | Anthropic-compatible messages endpoint; env leg: `HISTORIAN_TRANSLATE_ENDPOINT` |
25
- | `translate.model` | string | unset | **no device model is shipped in the package** (L-MACHINE-LOCAL, owner ruling 2026-10-01); set your own; env leg: `HISTORIAN_TRANSLATE_MODEL`; an unset model fails loudly at first use |
26
- | `translate.providerKey` | string | unset | jsonc fallback leg reading `provider[<key>].options.apiKey` |
27
- | `sections` / `locales` / `readingLoop` / `capture.enabled` | — | see README.md table | mirrored in the Chinese doc |
28
-
29
- Credential resolution order: `translate.apiKey` → `DASHSCOPE_API_KEY` →
30
- provider leg. With the whole chain unset the translation-backed tools stay
31
- disabled by design — the plugin never half-works.
32
-
33
- ## Behavior notes
34
- - Path segments must not look like locale codes; page ops take path+locale, no raw ids.
35
- - Evidence tier (`_meta/`, `_evidence/`) writes are monolingual `en`, unpublished-friendly, machine-owned.
36
- - Every tool result carries en/zh URLs; report them to the operator verbatim.
37
-
38
- ## Development
39
- `npm run build` → `npx vitest run` → `node tools/privacy-audit.mjs` →
40
- `node tools/portable-binding-audit.mjs` (guards the no-device-pin rule on
41
- portable surfaces). Releases: see `RELEASE.md` (npm trusted publishing via
42
- GitHub Actions OIDC; no long-lived tokens).
43
-
44
- ## Provenance
45
- Clean-room implementation per the institutional-memory contract; incident
46
- history and rulings live in the operator wiki (`infra/*`, `_evidence/*`).
8
+
9
+ One plugin that gives an OpenCode agent a curated memory layer on a Wiki.js
10
+ instance. Pages are written as structured, genre-typed entries.
11
+ Every write reports back both the English and Chinese URLs.
12
+
13
+ ## Why it exists
14
+
15
+ A machine run by one human and a fleet of AI agents forgets everything.
16
+ Sessions end; the details scroll away. Context compresses; facts are lost.
17
+
18
+ What was deployed, what broke, what was decided — months later nobody can
19
+ look it up. The historian makes machine history findable again.
20
+
21
+ Its writing rules are distilled from five wiki cultures plus SRE
22
+ postmortem practice. The full digest lives in
23
+ `docs/research/cross-cultural-wiki-writing-digest.md`.
24
+
25
+ ## What it does
26
+
27
+ - 11 `historian_*` tools: create, update, append, read, search, delete, move.
28
+ - Plus map, timeline, maintenance sweeps, migration, translation, anchoring.
29
+ - Genre skeletons G1–G6: incident retros, comparisons, checklists, concepts,
30
+ state ledgers, how-to guides.
31
+ - Bilingual twins (en/zh) translated automatically; you configure the engine.
32
+ - Every write must report two accessible URLs, en and zh.
33
+ - Migration gate: reformat old pages with a dry-run score first.
34
+ - `/historian-capture` turns the current session into an incident page.
35
+
36
+ ## Quick start
37
+
38
+ 1. Add the package to the `plugin` array in `opencode.jsonc`.
39
+ 2. Set the wiki URL and the path to your API key file.
40
+ 3. Talk naturally: "service-a OOM'd today; cache had no cap; record it."
41
+
42
+ The historian triages, picks a genre, runs its self-check, writes, and
43
+ returns both URLs.
44
+
45
+ ```jsonc
46
+ ["opencode-wiki-historian", {
47
+ "baseUrl": "http://<your-wiki>:3000",
48
+ "apiKeyPath": "~/.wiki-key"
49
+ }]
50
+ ```
51
+
52
+ The translation leg is optional. Unset, twins stay pending and no network
53
+ calls are made.
54
+
55
+ ## Install
56
+
57
+ **npm (recommended).** The package is `opencode-wiki-historian`. The repo and
58
+ the npm name differ on purpose.
59
+
60
+ ```jsonc
61
+ { "plugin": ["opencode-wiki-historian"] }
62
+ ```
63
+
64
+ **Local path (development).** Point at a checkout; edits apply immediately.
65
+
66
+ ```jsonc
67
+ { "plugin": ["file:///home/<you>/workspace/opencode-historian"] }
68
+ ```
69
+
70
+ Verify with `opencode run --command historian --message "historian_map show"`.
71
+ Eleven `historian_*` tools mean success. Upgrading from v2? Disable the old
72
+ flat skill file first; the mapping table is in [DEVELOPMENT.md](DEVELOPMENT.md).
73
+
74
+ ## Configuration
75
+
76
+ | option | default | note |
77
+ |---|---|---|
78
+ | `baseUrl` | `http://localhost:3000` | your wiki.js root |
79
+ | `apiKeyPath` | `~/.wikijs-api-key` | token file path |
80
+ | `translate.endpoint` | unset | translation API address |
81
+ | `translate.model` | unset | unset fails loudly on first use |
82
+ | `translate.apiKey` | unset | three sources, first wins |
83
+ | `translate.providerKey` | unset | reads a provider leg from opencode config |
84
+ | `sections` | `[]` (no limit) | write-prefix allowlist |
85
+ | `locales` | `["en","zh"]` | enabled languages |
86
+ | `readingLoop` | `false` | "check the wiki first" nudge |
87
+ | `capture.enabled` | `false` | idle reminder only |
88
+
89
+ No device model or gateway address ships inside the package. Set your own.
90
+
91
+ `sections`, when non-empty, is enforced: out-of-section writes are rejected
92
+ before any request is sent, naming the offending first segment.
93
+
94
+ `readingLoop` needs two signals: the option set to true, and a human-written
95
+ sentinel file. Either missing, it stays off; deleting the sentinel reverts
96
+ it instantly. An agent cannot enable it itself. Key resolution chains and
97
+ degradation details: see [DEVELOPMENT.md](DEVELOPMENT.md).
98
+
99
+ ## Prerequisites (Wiki.js side)
100
+
101
+ The plugin never performs admin operations for you. Before installing:
102
+
103
+ - Enable namespacing; `en` and `zh` in Active Namespaces.
104
+ - Create an API token (Admin > API Access) covering page read/write/delete.
105
+ - Put the token in the `apiKeyPath` file, or in `WIKIJS_API_KEY`.
106
+ - Group page rules must cover your `sections` prefixes.
107
+ - Comments off is recommended for a knowledge base.
108
+
109
+ ## Reading the Chinese pages
110
+
111
+ Chinese pages live under `/zh/<path>`; English pages have no prefix.
112
+ Every write result carries both URLs. If the language switcher is missing,
113
+ check the namespacing settings.
114
+
115
+ ## Genres and the index layer
116
+
117
+ | genre | question it answers | skeleton in one line |
118
+ |---|---|---|
119
+ | G1 incident | what happened | timeline → root cause → impact → actions |
120
+ | G2 comparison | which one | sources + table + verdict |
121
+ | G3 checklist | where to start | checkable items |
122
+ | G4 concept | what and why | definition → diagram → examples |
123
+ | G5 ledger | what runs now | one row per component, with verify date |
124
+ | G6 runbook | how to finish a task | action + expectation + failure path |
125
+
126
+ Every write passes a 10-item self-check: short sentences, enumerations as
127
+ tables, timelines with a source column, both URLs reported. Full rules:
128
+ [DEVELOPMENT.md](DEVELOPMENT.md).
129
+
130
+ ## Three content tiers
131
+
132
+ | tier | where | purpose |
133
+ |---|---|---|
134
+ | human | topic sections | distilled, bilingual, indexed |
135
+ | backstage | `_meta/` plus local mirror | machine bookkeeping |
136
+ | evidence | `_evidence/` | raw logs and transcripts; hidden from anonymous readers |
137
+
138
+ An over-long code block in a human page earns a polite advisory to move it
139
+ to the evidence tier. Advisories never block a write.
140
+
141
+ ## Known limitations
142
+
143
+ | fact | status |
144
+ |---|---|
145
+ | Translation tools disabled when no key resolves | by design; fill config to restore |
146
+ | Self-evolution drivers default off; not lit on the author's machine | honest state; code and tests ready, docs do not pretend |
147
+ | npm name differs from repo name | `opencode-historian` was taken by an unrelated package |
148
+
149
+ ## Decoupled from any machine
150
+
151
+ - No real hosts, real taxonomies, or page data ship inside.
152
+ - Translation address ships unset; unset means pending, never a network call.
153
+ - Every shipped file passes a privacy redline scan before publish; a hit
154
+ blocks the release.
155
+ - All examples are placeholders: `http://<your-wiki>:3000`, `team-notes/`.
156
+
157
+ ## More
158
+
159
+ Development internals, release process, and the v2 migration map:
160
+ [DEVELOPMENT.md](DEVELOPMENT.md). License: MIT.