feat(vault): default vault install to the published compmech vault

.github/workflows/release.yml

@@ -59,6 +59,7 @@ jobs:
           uv build --package akms-learn --out-dir dist/packages
           uv build --package akms-nodes-gen --out-dir dist/packages
           uv build --package akms-failure-memory --out-dir dist/packages
+          uv build --package compmech-reference-pack --out-dir dist/packages
           uv run --with twine twine check dist/packages/*
           sha256sum dist/packages/* > dist/SHA256SUMS
 
@@ -131,6 +132,8 @@ jobs:
             prefix: "akms_nodes_gen-"
           - package: akms-failure-memory
             prefix: "akms_failure_memory-"
+          - package: compmech-reference-pack
+            prefix: "compmech_reference_pack-"
     steps:
       - name: Download the verified distributions
         uses: actions/download-artifact@v8.0.1

docs/getting-started/akms/installation.md

@@ -12,70 +12,125 @@
 
 Use Python 3.12 for a complete-workspace environment.
 
-## Source checkout
-
-The documentation currently assumes a repository checkout rather than a PyPI
-release.
-
-### Core package only
+## Install from PyPI
 
 ```bash
-uv sync --project Packages/AKMS --all-extras --all-groups
-uv run --project Packages/AKMS akms --help
+pip install akms
+akms --help
 ```
 
-### Complete workspace
+That is the deterministic core: graph compilation, task-context resolution,
+loadouts and the CLI. The companion packages are independent installs:
 
 ```bash
-uv sync --all-packages --all-extras --all-groups
+pip install akms-learn                # learning-packet compiler
+pip install akms-nodes-gen            # node generation and validation tooling
+pip install akms-failure-memory       # project-owned failure memory
+pip install compmech-reference-pack   # computational-mechanics companion adapter
 ```
 
-The root workspace path-sources `mechdsl-core` and `algo2code` from the sibling
-checkout `../MechDSL`. A complete all-extras sync therefore requires that
-layout. Use the package-scoped command for core work when the sibling adapter
-repository is absent.
+`compmech-reference-pack` bridges computational-mechanics learning packets to
+the [MechDSL](https://github.com/CEmM2/MechDSL) executable backend. The compile
+and verify path is an extra, so the backend is not pulled in unless you ask
+for it:
 
-## Global vault
+```bash
+pip install "compmech-reference-pack[mechdsl]"
+```
 
-The default global node directory is:
+The optional embedded coding-agent runtime is an extra rather than a separate
+package:
 
-```text
-~/.claude/akms/nodes/
+```bash
+pip install "akms[orchestration]"
 ```
 
-Vault resolution precedence is:
+## Global vault
+
+AKMS compiles a graph from two inputs: nodes local to your repository, and a
+**global vault** of shared nodes. The vault is a directory of Markdown nodes
+resolved in this order:
 
 1. Explicit Python argument
 2. `AKMS_GLOBAL_VAULT`
 3. `global_vault` in `knowledge/graph/propagation_config.yaml`
-4. The default above
+4. `~/.claude/akms/nodes/`
 
-The graph compiler tolerates a missing or empty vault. Create it manually when
-you intend to use shared nodes:
+**No vault ships inside the `akms` package.** A vault is content with its own
+life cycle — nodes are added, corrected and forked far more often than code is
+released — so vaults are distributed separately and installed deliberately.
+Check what you have:
 
 ```bash
-mkdir -p ~/.claude/akms/nodes
+akms vault status
 ```
 
-Automated AKMS operations treat this directory as read-only.
+With no argument, `vault install` fetches the canonical computational-mechanics
+vault — [`CEmM2/akms-vault-compmech`](https://github.com/CEmM2/akms-vault-compmech),
+264 nodes covering computational mechanics, micromechanics, constitutive
+modelling, phase-field fracture, solvers and the MOOSE framework:
+
+```bash
+akms vault install
+```
 
-## Verify the core CLI
+The default is pinned to a release tag, so it installs the same content today
+and in a year. To install a different vault, pass a directory, a `.tar.gz`, or
+an https URL to a released archive:
 
 ```bash
-uv run --project Packages/AKMS akms --help
-uv run --project Packages/AKMS akms status --repo .
+akms vault install ./my-vault
+akms vault install https://example.org/vault-v2.0.0.tar.gz
+```
+
+`vault install` refuses to replace a vault that already holds nodes unless you
+pass `--force`, and refuses a source whose Markdown declares no `akms_schema`.
+Use `--dest` to install somewhere other than the resolved location.
+
+The graph compiler tolerates a missing or empty vault, so AKMS is usable
+against repository-local nodes alone. Aside from `vault install`, which you run
+yourself, automated AKMS operations treat this directory as read-only.
+
+## Source checkout
+
+For contributing, or to run against unreleased code:
+
+```bash
+git clone https://github.com/CEmM2/AKMS
+cd AKMS
+uv sync --all-packages --all-extras --all-groups
+```
+
+To work on the core package alone:
+
+```bash
+uv sync --project packages/akms --all-extras --all-groups
+uv run --project packages/akms akms --help
+```
+
+## Verify
+
+```bash
+akms --help
+akms status --repo .
+akms vault status
 ```
 
 `status` reports the graph inputs it can find; it does not require a non-empty
 global vault.
 
 ## Optional external tools
 
-- `qmd` is an external search binary. The core package pins the expected version
-  in package metadata and falls back through its wrapper when unavailable.
-- `repo2md` is invoked only through its configured CLI contract by the
-  `repo2md` mirror provider.
-- `nlm` is an external NotebookLM CLI used by selected node-generation and
+None of these are installed by AKMS, and none are required.
+
+- **`qmd`** — an external search binary used to rank node and mirror content.
+  The wrappers detect it and fall back to `grep` when it is absent.
+- **`repo-wiki`** — required only by the `repo2md` mirror provider. Code mirrors
+  default to the `legacy` provider, an in-process Python AST projection that
+  needs nothing external, so this matters only if you explicitly configure
+  `mirror.provider: repo2md`. See
+  [Code-mirror providers](../../reference/akms/user-guide/mirror_providers.md).
+- **`nlm`** — an external NotebookLM CLI used by selected node-generation and
   learning-provider workflows.
-- Claude/Codex CLI executables are required only for their corresponding
-  optional pipeline backends.
+- **Claude / Codex CLI** — required only by their corresponding optional
+  pipeline backends.

docs/getting-started/nodes-gen/install.md

@@ -23,7 +23,7 @@ From the AKMS repo root:
 
 ```bash
 # 1. Resolve and install dependencies for the AKMS_nodes_gen workspace member
-uv sync --project Packages/AKMS_nodes_gen
+uv sync --project packages/akms_nodes_gen
 ```
 
 `uv sync` builds the editable install and pulls in `fastapi`, `uvicorn`,
@@ -34,7 +34,7 @@ uv sync --project Packages/AKMS_nodes_gen
 If you want the `akms-pick` command available from anywhere on your `PATH`:
 
 ```bash
-uv tool install --editable Packages/AKMS_nodes_gen
+uv tool install --editable packages/akms_nodes_gen
 ```
 
 That installs two equivalent executables — `akms-pick` (short) and
@@ -45,7 +45,7 @@ That installs two equivalent executables — `akms-pick` (short) and
 === "After uv sync (per-project)"
 
     ```bash
-    uv --project Packages/AKMS_nodes_gen run akms-pick
+    uv --project packages/akms_nodes_gen run akms-pick
     ```
 
 === "After uv tool install (global)"
@@ -57,7 +57,7 @@ That installs two equivalent executables — `akms-pick` (short) and
 === "Module-style fallback"
 
     ```bash
-    uv --project Packages/AKMS_nodes_gen run \
+    uv --project packages/akms_nodes_gen run \
         python -m akms_nodes_gen.batch_picker
     ```
 

docs/index.md

@@ -37,13 +37,13 @@ omnivorous agent framework:
     Batch Picker and generation tools for turning source collections into
     validated AKMS nodes, including a NotebookLM CLI path.
 
--   :material-function-variant: __[Companion adapters](architecture/modules.md)__
+-   :material-function-variant: __[compmech-reference-pack](architecture/modules.md)__
 
     ---
 
-    Executable-domain bridges such as `compmech-reference-pack`, which maps
-    computational-mechanics LSP excerpts onto the MechDSL backend while
-    preserving provenance.
+    Companion adapter that maps computational-mechanics LSP excerpts onto the
+    MechDSL executable backend while preserving provenance. The compile path is
+    an optional extra.
 
 </div>
 

docs/reference/akms/dev-guide/setup.md

@@ -13,8 +13,8 @@
 ```bash
 git clone <repository-url>
 cd AKMS
-uv sync --project Packages/AKMS --all-extras --all-groups
-uv run --project Packages/AKMS pytest Packages/AKMS/tests/akms -q
+uv sync --project packages/akms --all-extras --all-groups
+uv run --project packages/akms pytest packages/akms/tests/akms -q
 ```
 
 ## Whole workspace

docs/reference/akms/dev-guide/testing.md

@@ -7,9 +7,9 @@ useful test, which is an oddly self-defeating quality metric.
 ## Core
 
 ```bash
-uv run --project Packages/AKMS pytest Packages/AKMS/tests/akms -q
-uv run --project Packages/AKMS pytest Packages/AKMS/tests/e2e -q
-uv run --project Packages/AKMS pytest Packages/AKMS/tests/plan_tests -q
+uv run --project packages/akms pytest packages/akms/tests/akms -q
+uv run --project packages/akms pytest packages/akms/tests/e2e -q
+uv run --project packages/akms pytest packages/akms/tests/plan_tests -q
 ```
 
 Markers declared by the core package include `unit`, `integration`,
@@ -31,8 +31,8 @@ uv run --project packages/akms_learn pytest \
 ## Node generation
 
 ```bash
-uv run --project Packages/AKMS_nodes_gen pytest \
-  Packages/AKMS_nodes_gen/tests -q
+uv run --project packages/akms_nodes_gen pytest \
+  packages/akms_nodes_gen/tests -q
 ```
 
 ## compmech reference pack

docs/reference/akms/user-guide/failure_memory_public_api.md

@@ -4,7 +4,7 @@ The optional `akms-failure-memory` package may depend only on documented public
 AKMS contracts. The machine-readable pin lives at:
 
 ```text
-Packages/AKMS/release/failure_memory_public_api_pin.json
+packages/akms/release/failure_memory_public_api_pin.json
 ```
 
 ## Permitted surface
@@ -36,5 +36,5 @@ test stops complaining.
 ## Stability test
 
 ```bash
-uv run pytest Packages/AKMS/tests/akms/test_failure_memory_public_api_pin.py -q
+uv run pytest packages/akms/tests/akms/test_failure_memory_public_api_pin.py -q
 ```

docs/reference/akms/user-guide/mirror_providers.md

@@ -4,6 +4,12 @@ AKMS projects repository source into `knowledge/code-mirror/` for exact path
 resolution, search, and review context. Projection is pluggable; graph and
 loadout semantics remain in AKMS core.
 
+A code mirror is **generated from your own repository**, not shipped with AKMS.
+Nothing arrives pre-populated and there is nothing to download: you produce one
+with `akms generate-mirror` and refresh it as the source changes. A mirror is
+build output, and like build output it belongs to the tree it was projected
+from.
+
 ## Defaults
 
 | Setting | Default | Meaning |
@@ -35,18 +41,28 @@ The command is an argv prefix, not a shell string.
 
 ## `legacy`
 
+The default, and the only provider that works out of the box — it is
+in-process and needs nothing installed beyond `akms` itself.
+
 - Python-only AST projection
 - In-process implementation
 - Changed-file selection by default
 - Structural drift analysis on the deterministic path
 
 ## `repo2md`
 
+Requires the external `repo-wiki` executable, which **AKMS does not install**.
+It is registered lazily and invoked only when you configure
+`mirror.provider: repo2md`, so its absence costs nothing until then. Because
+`mirror.fallback_on_error` defaults to `false`, configuring this provider
+without the binary present fails loudly rather than silently reverting to
+`legacy` — set that flag to `true` if you would rather it fell back.
+
 - Invokes `repo-wiki export-akms` with `shell=False`
 - Does not import repo2md as a Python package
 - Validates export schema, AKMS v2 frontmatter, output containment,
   content/source consistency, duplicate IDs, and completeness
-- Uses a pinned consumer contract under `Packages/AKMS/release/`
+- Uses a pinned consumer contract under `packages/akms/release/`
 
 ## CLI
 

docs/reference/nodes-gen/batch-picker/configuration.md

@@ -7,8 +7,8 @@ Every path is overridable via an environment variable.
 
 | Env var | Default | What it points at |
 |---------|---------|-------------------|
-| `AKMS_REPO_ROOT` | Auto-detected (`Packages/AKMS_nodes_gen/src/akms_nodes_gen/batch_picker/config.py` walked up 5 levels) | The AKMS monorepo root — base for the other defaults |
-| `AKMS_PLAN_MD` | `<repo>/Packages/AKMS_nodes_gen/generation_plan.md` | Markdown file the parser reads |
+| `AKMS_REPO_ROOT` | Auto-detected (`packages/akms_nodes_gen/src/akms_nodes_gen/batch_picker/config.py` walked up 5 levels) | The AKMS monorepo root — base for the other defaults |
+| `AKMS_PLAN_MD` | `<repo>/packages/akms_nodes_gen/generation_plan.md` | Markdown file the parser reads |
 | `AKMS_BBT_JSON` | `~/ZotSums/zsumbib.json` | BetterBibTeX export with all paper metadata + PDF paths |
 | `AKMS_ZOTSUMS_ROOT` | `~/ZotSums` | ZotSums Obsidian vault (Papers/, Collections/) |
 | `AKMS_BATCH_STATE` | `<repo>/Sources_Evals/NLM/batch_assignments.json` | Per-batch citekey assignments + NLM metadata |

docs/reference/nodes-gen/batch-picker/data-sources.md

@@ -136,7 +136,7 @@ from a tooling perspective.
 
 ## 3. `generation_plan.md` (the batch plan)
 
-Default: `Packages/AKMS_nodes_gen/generation_plan.md`. Override with
+Default: `packages/akms_nodes_gen/generation_plan.md`. Override with
 `AKMS_PLAN_MD`.
 
 The parser is intentionally lenient about ordering and tolerates extra

docs/reference/nodes-gen/development.md

@@ -7,27 +7,27 @@ How to extend, test, and contribute to the package.
 ```bash
 git clone git@github.com:the AKMS repository.git
 cd AKMS
-uv sync --project Packages/AKMS_nodes_gen
+uv sync --project packages/akms_nodes_gen
 ```
 
 For docs work, also pull in the `docs` group:
 
 ```bash
-uv sync --project Packages/AKMS_nodes_gen --group docs
+uv sync --project packages/akms_nodes_gen --group docs
 ```
 
 ## Running the docs locally
 
 ```bash
-uv --project Packages/AKMS_nodes_gen run --group docs mkdocs serve -f Packages/AKMS_nodes_gen/mkdocs.yml
+uv --project packages/akms_nodes_gen run --group docs mkdocs serve -f packages/akms_nodes_gen/mkdocs.yml
 ```
 
 Opens at `http://127.0.0.1:8000/`. Live-reloads on save.
 
 ## Running the picker in dev mode
 
 ```bash
-uv --project Packages/AKMS_nodes_gen run akms-pick --reload
+uv --project packages/akms_nodes_gen run akms-pick --reload
 ```
 
 `--reload` enables uvicorn's file watcher; saving any `.py` under the
@@ -61,7 +61,7 @@ There is no `tests/` folder yet — adding one would be an easy win. The
 shape that fits this codebase:
 
 ```
-Packages/AKMS_nodes_gen/tests/
+packages/akms_nodes_gen/tests/
 └── batch_picker/
     ├── conftest.py          # shared fixtures (Paths, fake catalog)
     ├── test_plan_parser.py  # parse_plan against known plans + edge cases

docs/reference/nodes-gen/tools/akms-node-promote.md

@@ -5,7 +5,7 @@ vault (`~/.claude/akms/nodes/`) with domain-based subdirectory nesting.
 
 ## Location
 
-`Packages/AKMS_nodes_gen/src/akms_nodes_gen/akms_node_promote.py`
+`packages/akms_nodes_gen/src/akms_nodes_gen/akms_node_promote.py`
 
 ## Run it