@follenfang/wowdoc 0.0.5 → 0.0.7

package/README.md

@@ -110,9 +110,10 @@ Local state lives under `~/.wowdoc`:
 ```text
 config/         versioned source catalog and local configuration
 repositories/   complete bare Git mirrors
-objects/        content-addressed source and asset bytes
-ast/            auditable per-file JSON syntax trees
-indexes/        one WAL SQLite database per product branch
+objects/        legacy content objects plus immutable Pack storage
+objects/packs/  sequential Pack segments and their catalog
+ast/            auditable legacy per-file syntax trees (new builds use Pack)
+indexes/        one shared content DB plus one WAL SQLite database per product branch
 manifests/      immutable snapshot manifests
 state/          initialization and task state
 tmp/worktrees/  leased detached worktrees used only while parsing
@@ -120,7 +121,20 @@ locks/          repository and snapshot build locks
 logs/           local diagnostics
 ```
 
-Each parser task fixes the requested ref to a Commit and creates its own detached worktree. Published queries never depend on that worktree. Identical Git blobs and AST objects are reused across Tags and branches, while snapshot relationships remain isolated by product and Commit.
+Each parser task fixes the requested ref to a Commit and creates its own detached worktree. Published queries never depend on that worktree. Identical Git blobs and AST objects are written once to immutable Pack segments and reused across Tags and branches, while snapshot relationships remain isolated by product and Commit.
+
+Source objects, AST and assets are appended to one staging Pack per build and atomically published; the Pack catalog verifies original length and SHA-256 on every read. Legacy raw/gzip objects remain readable. One source-level SQLite keeps immutable facts and search-document metadata per content hash, while each product branch keeps its own WAL snapshot mappings and local FTS corpus so BM25 ordering remains branch-equivalent. A full-text hit is resolved back to the exact Pack source line. Initialization downloads up to three source mirrors in parallel, then parses with the normal 4-8 worker budget.
+
+### Performance baseline
+
+Measured on Windows 11, Git 2.53.0, the same `wow-ui-source` Retail Commit `c878310d8432a65bac029c7bacc24eeb2e662bbe`, 8 parser workers, and a complete local bare mirror:
+
+| Build | Cold build time | Indexed files | SQLite | Home total |
+| --- | ---: | ---: | ---: | ---: |
+| `b201d38` baseline | 41.1 s | 3,685 | 158,629,888 B | 352,202,349 B |
+| compact pipeline | 11.4 s | 3,685 | 67,743,744 B | 169,972,173 B |
+
+The cold parse/index stage is 3.61x faster (about 72% less time), its SQLite is 57% smaller, and its complete home is 52% smaller. A separate 10-Tag run produced 196,460,544 B of branch SQLite and 342,740,177 B total while preserving complete Lua/XML full-text coverage. Exact symbol, plain-text source, relation, Commit, path, line, excerpt, and SHA-256 checks pass after the storage changes. These are local measurements; network clone/fetch time varies by GitHub and TLS conditions.
 
 ## Agent integration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@follenfang/wowdoc",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Auditable WoW UI source intelligence CLI for coding agents",
   "license": "MIT",
   "type": "module",

package/skill/SKILL.md

@@ -15,4 +15,6 @@ Translate the user's wording into explicit `source`, `product`, `ref`, `topic`,
 6. Do not apply latest fallback to `ambiguous_version`, `unsupported_build`, `ref_not_found`, or update failures.
 7. Cite `sourceId`, product, Tag when present, resolved Commit, path, line, and the returned excerpt. Treat `dynamic-unresolved` edges as unresolved, not exact.
 
+The data directory defaults to `~/.wowdoc`. `WOWDOC_HOME` may override it with another writable path for an isolated workspace, another drive, or a server deployment. This changes only wowdoc's source, index, object, lock, and log storage; it does not change the npm installation directory or the Skill directory. Run `wowdoc doctor` to see the resolved data directory.
+
 Read [source-catalog.md](references/source-catalog.md) for source/product names and [commands.md](references/commands.md) for command selection.

package/skill/references/commands.md

@@ -13,6 +13,35 @@ wowdoc source sync  --source SOURCE --product PRODUCT
 wowdoc index build  --source SOURCE --product PRODUCT --ref REF
 wowdoc index refresh --source SOURCE --product PRODUCT --ref REF
 wowdoc index status --source SOURCE --product PRODUCT
+wowdoc init
+wowdoc doctor
+wowdoc update --dry-run
+wowdoc clean
+wowdoc clean --yes
+wowdoc uninstall
+wowdoc uninstall --yes
 ```
 
 Use exact qualified identifiers when known. For natural-language questions, select a topic and use the narrowest stable identifier, event, template, TOC field, asset path, or API name present in the question. Prefer results marked `exact_symbol`; verify relationship confidence and retain the returned excerpt as evidence.
+
+## Data directory
+
+Without configuration, all source mirrors, objects, indexes, manifests, locks, logs, and temporary worktrees live under `~/.wowdoc`.
+
+Use another writable directory by setting `WOWDOC_HOME` before invoking wowdoc. PowerShell:
+
+```powershell
+$env:WOWDOC_HOME = 'D:\WOWData\wowdoc'
+wowdoc doctor
+wowdoc init
+```
+
+Bash or zsh:
+
+```bash
+export WOWDOC_HOME="$HOME/wowdoc-data"
+wowdoc doctor
+wowdoc init
+```
+
+The override applies to every wowdoc command launched from that environment. `wowdoc doctor` reports the resolved `home`. The npm package remains in the npm global prefix, and the Skill remains in `~/.agents/skills/wowdoc`.