aiwg 2026.7.12 → 2026.7.13

package/README.md

@@ -499,6 +499,9 @@ aiwg use research          # Research workflow automation (8 agents, 8-stage pip
 aiwg use rlm               # RLM addon (recursive context decomposition)
 aiwg use all               # Everything
 
+# Existing projects: re-analyze and refresh the provider context bridge
+aiwg regenerate
+
 # Or scaffold a new project
 aiwg new my-project
 

package/agentic/code/frameworks/research-complete/lint/citation-resolves.yaml

@@ -1,10 +1,9 @@
 id: research/citation-resolves
 name: Citation reference integrity
-description: Every REF-XXX reference in body text points to an existing note in findings/
+description: Every REF reference in body text points to an existing note in the lint target
 severity: error
 applies-to:
   glob: "**/*.md"
 checks:
   - type: reference-resolves
-    referencePattern: "REF-\\d{3}"
-    basePath: findings
+    referencePattern: "\\bREF-\\d{3,}\\b"

package/agentic/code/frameworks/research-complete/skills/research-lint/SKILL.md

@@ -12,7 +12,7 @@ commandHint:
 
 # Research Lint
 
-Run the research corpus lint ruleset against `.aiwg/research/` to detect structural and referential integrity issues.
+Run the research corpus lint ruleset against the configured corpus to detect structural and referential integrity issues.
 
 ## Triggers
 
@@ -26,7 +26,12 @@ Run the research corpus lint ruleset against `.aiwg/research/` to detect structu
 ## Parameters
 
 ### `[target]` (optional)
-Path to lint. Defaults to `.aiwg/research/`.
+Path to lint. When omitted, resolve the target in this order:
+
+1. `<AIWG_CORPUS_ROOT>/documentation/references/` when `AIWG_CORPUS_ROOT` is set.
+2. `<research.corpusRoot>/documentation/references/` when `.aiwg/aiwg.config` configures a corpus root.
+3. `documentation/references/` when the canonical warehouse layout exists in the project.
+4. `.aiwg/research/` for legacy project-local corpora.
 
 ### `--fix` (optional)
 Attempt auto-fixes for fixable issues (add missing frontmatter defaults, correct formatting).
@@ -44,10 +49,10 @@ Severity threshold for failure: `error` (default), `warn`, or `info`.
 
 ### Phase 1: Run Lint
 
-Execute the lint runner against the research corpus:
+Resolve the default target as described above, then execute the lint runner against the research corpus:
 
 ```bash
-aiwg lint .aiwg/research/ --ruleset research --format full
+aiwg lint <resolved-target> --ruleset research --format full
 ```
 
 This checks all 11 rules in the research ruleset:
@@ -57,7 +62,7 @@ This checks all 11 rules in the research ruleset:
 | `ref-frontmatter` | error | Required frontmatter fields present |
 | `ref-id-unique` | error | No duplicate REF-XXX identifiers |
 | `ref-id-format` | warn | REF identifiers follow `REF-NNN` naming |
-| `citation-resolves` | error | REF-XXX references point to existing notes |
+| `citation-resolves` | error | Whole REF IDs point to exact or slugged notes anywhere in the lint target |
 | `grade-present` | warn | GRADE quality assessment in frontmatter |
 | `provenance-present` | warn | Provenance metadata present |
 | `cross-ref-bidirectional` | info | Related refs linked both ways |

package/agentic/code/frameworks/sdlc-complete/templates/openhuman/AGENTS.md.aiwg-template

@@ -23,8 +23,8 @@ npm run lint
 ## AIWG SDLC Framework
 
 This project uses [AIWG](https://aiwg.io) for SDLC orchestration. OpenHuman is
-AIWG-convention-aware: agent personas live in `.agents/agents/`, skills in
-`.openhuman/skills/`, and this file is the Discover-First bridge.
+AIWG-convention-aware: kernel skills live in `~/.openhuman/skills/`, rule bodies
+in `~/.openhuman/.aiwg/rules/`, and this file is the Discover-First bridge.
 
 ### Discover-First Protocol
 
@@ -41,17 +41,18 @@ corpus, not just the kernel set surfaced here.
 
 ### Skills
 
-Kernel skills deploy to `.openhuman/skills/` (OpenHuman's project-scope native
-scan root); standard skills are sequestered under `.openhuman/.aiwg/skills/`
-for index-driven discovery. Redeploy or refresh with:
+Kernel skills deploy to `~/.openhuman/skills/` (OpenHuman's user-scope native
+scan root). Standard skills stay in AIWG's index-driven discovery system rather
+than being copied into an OpenHuman scan root. Redeploy or refresh with:
 
 ```bash
 aiwg use sdlc --provider openhuman
 aiwg refresh --provider openhuman
 ```
 
-Project-scope skill discovery requires the workspace trust marker under
-`.openhuman/` — see the quickstart.
+The default deploy emits no markdown persona copies. Curated OpenHuman-native
+TOML workers are optional via `--harness-agents` and land under
+`~/.openhuman/agents/`.
 
 ### Commands & Rules
 
@@ -59,8 +60,8 @@ OpenHuman has no native command surface; AIWG commands surface through this
 `AGENTS.md` bridge and the deployed command-skills. Rule full bodies are on
 disk under `.openhuman/.aiwg/rules/` and reachable via `aiwg show rule <name>`.
 
-CRITICAL/HIGH rules are deployed to disk as always-on bodies. The MEDIUM/LOW
-tier is on-demand only — listed below, fetched via `aiwg show rule <name>`.
+CRITICAL/HIGH rules are rendered into the active context. The MEDIUM/LOW tier
+is on-demand only — listed below, fetched via `aiwg show rule <name>`.
 
 {{ON_DEMAND_RULES}}
 

package/dist/src/lint/runner.js

@@ -28,10 +28,56 @@ function parseFrontmatter(content) {
     }
     return result;
 }
+const DEFAULT_REFERENCE_PATTERN = '\\bREF-\\d{3,}\\b';
+/**
+ * Build a target-wide artifact ID index once per lint run.
+ *
+ * Reference documents may use either an exact filename (`REF-001.md`) or the
+ * canonical slugged form (`REF-001-some-title.md`). Indexing the ID prefix also
+ * makes resolution independent of a particular corpus directory layout.
+ */
+function buildReferenceIndex(allFiles) {
+    const references = new Set();
+    for (const file of allFiles) {
+        if (path.extname(file).toLowerCase() !== '.md')
+            continue;
+        const basename = path.basename(file, '.md');
+        if (/^REF-\d+-(?:citations|radar)$/.test(basename))
+            continue;
+        references.add(basename);
+        const artifactId = basename.match(/^(.+?-\d+)(?:-|$)/);
+        if (artifactId)
+            references.add(artifactId[1]);
+    }
+    return references;
+}
+/**
+ * Preserve support for references stored outside the lint target when a rule
+ * explicitly supplies basePath. Accept both exact and slugged filenames.
+ */
+function resolvesFromBasePath(refId, targetDir, basePath) {
+    const candidateDirs = new Set([
+        path.resolve(targetDir, basePath),
+        path.resolve(process.cwd(), basePath),
+    ]);
+    for (const dir of candidateDirs) {
+        try {
+            if (fs.existsSync(path.join(dir, `${refId}.md`)))
+                return true;
+            if (fs.readdirSync(dir).some(file => file.startsWith(`${refId}-`) && file.endsWith('.md'))) {
+                return true;
+            }
+        }
+        catch {
+            // Missing or unreadable candidate directories do not resolve the ID.
+        }
+    }
+    return false;
+}
 /**
  * Run a single check against a file's content and frontmatter
  */
-function runCheck(check, content, frontmatter, filePath, targetDir, allFiles) {
+function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, referenceIndex) {
     const diagnostics = [];
     switch (check.type) {
         case 'frontmatter-required': {
@@ -68,7 +114,7 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles) {
             break;
         }
         case 'reference-resolves': {
-            const refPattern = check.referencePattern || 'REF-\\d{3}';
+            const refPattern = check.referencePattern || DEFAULT_REFERENCE_PATTERN;
             const regex = new RegExp(refPattern, 'g');
             const lines = content.split('\n');
             for (let i = 0; i < lines.length; i++) {
@@ -76,20 +122,15 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles) {
                 while ((match = regex.exec(lines[i])) !== null) {
                     const refId = match[0];
                     const basePath = check.basePath || '.aiwg/research/findings';
-                    const refFile = path.join(targetDir, basePath, `${refId}.md`);
-                    if (!fs.existsSync(refFile)) {
-                        // Also check relative to cwd
-                        const altPath = path.join(process.cwd(), basePath, `${refId}.md`);
-                        if (!fs.existsSync(altPath)) {
-                            diagnostics.push({
-                                ruleId: '',
-                                ruleName: '',
-                                severity: 'error',
-                                file: filePath,
-                                message: `Reference '${refId}' does not resolve to an existing file`,
-                                line: i + 1,
-                            });
-                        }
+                    if (!referenceIndex.has(refId) && !resolvesFromBasePath(refId, targetDir, basePath)) {
+                        diagnostics.push({
+                            ruleId: '',
+                            ruleName: '',
+                            severity: 'error',
+                            file: filePath,
+                            message: `Reference '${refId}' does not resolve to an existing file`,
+                            line: i + 1,
+                        });
                     }
                 }
             }
@@ -149,7 +190,7 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles) {
             break;
         }
         case 'cross-ref-bidirectional': {
-            const refPattern = check.referencePattern || 'REF-\\d{3}';
+            const refPattern = check.referencePattern || DEFAULT_REFERENCE_PATTERN;
             const regex = new RegExp(refPattern, 'g');
             const currentBasename = path.basename(filePath, '.md');
             const matches = content.match(regex) || [];
@@ -185,7 +226,7 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles) {
 /**
  * Run a single rule against all matching files in the target
  */
-async function runRule(rule, targetDir, allFiles) {
+async function runRule(rule, targetDir, allFiles, referenceIndex) {
     const diagnostics = [];
     // Filter files matching the rule's glob
     const ruleGlob = rule.appliesTo.glob;
@@ -226,7 +267,7 @@ async function runRule(rule, targetDir, allFiles) {
         for (const check of rule.checks) {
             if (check.type === 'id-unique')
                 continue; // Already handled
-            const checkDiagnostics = runCheck(check, content, frontmatter, file, targetDir, allFiles);
+            const checkDiagnostics = runCheck(check, content, frontmatter, file, targetDir, allFiles, referenceIndex);
             for (const d of checkDiagnostics) {
                 d.ruleId = rule.id;
                 d.ruleName = rule.name;
@@ -286,10 +327,11 @@ function autoDetectRulesets(target, available) {
 export async function runLint(targetDir, rulesets, options = {}) {
     const recursive = options.recursive ?? true;
     const allFiles = await collectFiles(targetDir, recursive);
+    const referenceIndex = buildReferenceIndex(allFiles);
     const allDiagnostics = [];
     for (const ruleset of rulesets) {
         for (const rule of ruleset.rules) {
-            const diagnostics = await runRule(rule, targetDir, allFiles);
+            const diagnostics = await runRule(rule, targetDir, allFiles, referenceIndex);
             allDiagnostics.push(...diagnostics);
         }
     }

package/docs/cli-reference.md

@@ -461,7 +461,7 @@ aiwg use sdlc --ci-hooks-enabled --dry-run
 | OpenCode | `opencode` | `.opencode/agent/`, `.opencode/commands/`, `.opencode/skill/`, `.opencode/rule/` | — |
 | Hermes | `hermes` | `~/.hermes/skills/`, `AGENTS.md` (lean) | — |
 | OpenClaw | `openclaw` | `~/.openclaw/agents/`, `~/.openclaw/commands/`, `~/.openclaw/skills/`, `~/.openclaw/rules/`, `~/.openclaw/behaviors/` | ✓ |
-| OpenHuman | `openhuman` | `.agents/agents/`, `~/.openhuman/skills/`, `~/.openhuman/.aiwg/{skills,rules}/`, `AGENTS.md` | — |
+| OpenHuman | `openhuman` | `~/.openhuman/skills/`, `~/.openhuman/.aiwg/rules/`, optional `~/.openhuman/agents/aiwg_*.toml`, project `AGENTS.md` | — |
 | Local/Ollama | `local` | Same as `claude` (local model, Claude Code paths) | — |
 
 **Commands → Skills migration:**
@@ -473,6 +473,7 @@ On first run after the commands-to-skills migration, `aiwg use` detects an exist
 - **Codex**: Commands and skills deploy to `~` (user-level) for availability across all projects; the provider ID is `codex`, not `openai`
 - **Windsurf**: Agents aggregated into `AGENTS.md` at project root; no separate agent files
 - **Warp**: Agents and commands also aggregated into `WARP.md` for single-file context loading
+- **OpenHuman**: Kernel skills and rule bodies are user-global; the default deploy emits no markdown persona copies. Project context is rendered into `AGENTS.md`, and curated native TOML agents are opt-in with `--harness-agents`.
 - **Hermes**: Not a spawnable CLI — access via `ollama run hermes3` or MCP sidecar; deploy sets up skills and a lean AGENTS.md
 - **OpenClaw**: Only provider with behaviors support (`~/.openclaw/behaviors/`); all artifacts deploy to home directory
 - **Local/Ollama**: Uses Claude Code path layout; specify `--coding-model ollama/<model>` to route coding tasks to the local model

package/docs/contributing/ci-cd-secrets.md

@@ -1,240 +1,153 @@
 # CI/CD Secrets Configuration
 
-**Version:** 2.0
-**Last Updated:** 2026-07-12
+**Version:** 3.0
+**Last Updated:** 2026-07-15
 **Target Audience:** Repository maintainers and administrators
 
-AIWG's Gitea CI/CD workflows use OpenBao for repository-managed secrets. Gitea
-Actions stores only the OpenBao bootstrap pair:
+AIWG's Gitea CI/CD workflows use vault for repository-managed secrets. Gitea
+Actions stores only the vault bootstrap pair:
 
 | Tracker secret | Purpose |
 |---|---|
-| `BAO_CI_ROLE_ID` | AppRole role ID for the `ci-aiwg` reader. |
-| `BAO_CI_SECRET_ID` | AppRole secret ID for the `ci-aiwg` reader. |
+| `VAULT_CI_ROLE_ID` | AppRole role ID for the `ci-aiwg` reader. |
+| `VAULT_CI_SECRET_ID` | AppRole secret ID for the `ci-aiwg` reader. |
 
 Do not recreate legacy Gitea secrets such as `NPM_TOKEN`, `GH_ACCESS_TOKEN`,
-`AIWG_IO_DISPATCH_TOKEN`, or `DEPLOY_SSH_KEY`. Those values live in OpenBao and
-are fetched at runtime with [`../../ci/openbao-fetch.sh`](../../ci/openbao-fetch.sh).
+`AIWG_IO_DISPATCH_TOKEN`, or `DOCSITE_DEPLOY_KEY`. Those values live in vault
+and are fetched at runtime with [`../../ci/vault-fetch.sh`](../../ci/vault-fetch.sh).
 
 `secrets.GITHUB_TOKEN` is not part of this migration. It is a per-run token
 issued by the CI system and is still used by PR-comment workflows.
 
-## OpenBao Fetch Specs
+## Vault Fetch Specs
 
 | Workflow | Spec | Exported value |
 |---|---|---|
-| `.gitea/workflows/npm-publish.yml` | `ci/openbao-fetch.npm-publish.spec` | `NODE_AUTH_TOKEN` |
-| `.gitea/workflows/gitea-release.yml` | `ci/openbao-fetch.gitea-release.spec` | `GITEA_TOKEN` |
-| `.gitea/workflows/upload-release-sigs.yml` | `ci/openbao-fetch.upload-release-sigs.spec` | `GITEA_TOKEN` |
-| `.gitea/workflows/github-mirror.yml` | `ci/openbao-fetch.github-mirror.spec` | `GH_TOKEN` |
-| `.gitea/workflows/notify-site.yml` | `ci/openbao-fetch.notify-site.spec` | `AIWG_IO_DISPATCH_TOKEN` |
-| `.gitea/workflows/docsite-deploy.yml` | `ci/openbao-fetch.docsite-deploy.spec` | `DEPLOY_SSH_KEY_FILE` |
+| `.gitea/workflows/npm-publish.yml` | `ci/vault-fetch.npm-publish.spec` | `NODE_AUTH_TOKEN` |
+| `.gitea/workflows/gitea-release.yml` | `ci/vault-fetch.gitea-release.spec` | `GITEA_TOKEN` |
+| `.gitea/workflows/upload-release-sigs.yml` | `ci/vault-fetch.upload-release-sigs.spec` | `GITEA_TOKEN` |
+| `.gitea/workflows/github-mirror.yml` | `ci/vault-fetch.github-mirror.spec` | `GH_TOKEN` |
+| `.gitea/workflows/notify-site.yml` | `ci/vault-fetch.notify-site.spec` | `AIWG_IO_DISPATCH_TOKEN` |
+| `.gitea/workflows/docsite-deploy.yml` | `ci/vault-fetch.docsite-deploy.spec` | `DOCSITE_DEPLOY_KEY_FILE` |
+
+The specs contain only `*_VAULT_PATH` and `*_VAULT_FIELD` placeholders. Concrete
+vault paths, metadata paths, hostnames, and fields are stored as private Gitea
+variables or in the private operations catalog.
 
 Validate specs without reading live secrets:
 
 ```bash
-for f in ci/openbao-fetch.*.spec; do
-  bash ci/openbao-fetch.sh --spec "$f" --dry-run
+for f in ci/vault-fetch.*.spec; do
+  bash ci/vault-fetch.sh --spec "$f" --dry-run
 done
 ```
 
-## Classification
-
-| Name | Class | Destination |
-|---|---|---|
-| `BAO_CI_ROLE_ID` | `BOOTSTRAP` | Gitea Actions secret |
-| `BAO_CI_SECRET_ID` | `BOOTSTRAP` | Gitea Actions secret |
-| `GITHUB_TOKEN` | CI-issued token | No storage; issued per run |
-| `NPM_TOKEN` | `SECRET` | `kv_internal/ci/aiwg/gitea-npm-token` field `token` |
-| `GH_ACCESS_TOKEN` | `SECRET` | `kv_internal/ci/aiwg/github-mirror-token` field `token` |
-| `AIWG_IO_DISPATCH_TOKEN` | `SECRET` | `kv_internal/ci/aiwg/aiwg-io-dispatch-token` field `token` |
-| `DEPLOY_SSH_KEY` | `SECRET` | `kv_internal/ci/shared/docs-deploy` field `private_key` |
-| `DEPLOY_HOST` | `CONFIG` | Gitea Actions variable |
-| `DEPLOY_PORT` | `CONFIG` | Gitea Actions variable |
-| `DEPLOY_USER` | `CONFIG` | Gitea Actions variable |
-| `DEPLOY_PATH` | `CONFIG` | Gitea Actions variable |
-
-## AppRole and Path Plan
-
-The reader AppRole is `ci-aiwg`. Its token TTL should stay short, with a
-maximum TTL no longer than the release jobs need.
-
-The machine-readable plan is [`../../ci/openbao-migration-plan.json`](../../ci/openbao-migration-plan.json).
-The AppRole policy file is [`../../ci/openbao-ci-aiwg.hcl`](../../ci/openbao-ci-aiwg.hcl).
-
-Required readable leaves:
-
-```text
-kv_internal/data/ci/aiwg/gitea-npm-token
-kv_internal/data/ci/aiwg/github-mirror-token
-kv_internal/data/ci/aiwg/aiwg-io-dispatch-token
-kv_internal/data/ci/shared/docs-deploy
-```
-
-Adjacent repository paths should deny access. Verify with the OpenBao operator
-runbook in `itops/docs/security/ci-secret-migration.md`.
-
 Run the local consistency gate:
 
 ```bash
-npm run lint:openbao-migration
+npm run lint:vault-migration
 ```
 
-After live leaves are provisioned, verify metadata without reading values:
-
-```bash
-npm run lint:openbao-migration -- --live
-```
-
-To induct leaf values from an approved local medium, prepare one file per leaf:
+## Classification
 
-```text
-ci__aiwg__gitea-npm-token.token
-ci__aiwg__github-mirror-token.token
-ci__aiwg__aiwg-io-dispatch-token.token
-ci__shared__docs-deploy.private_key
-```
+| Name | Class | Destination |
+|---|---|---|
+| `VAULT_CI_ROLE_ID` | `BOOTSTRAP` | Gitea Actions secret |
+| `VAULT_CI_SECRET_ID` | `BOOTSTRAP` | Gitea Actions secret |
+| `GITHUB_TOKEN` | CI-issued token | No storage; issued per run |
+| `GT_NPM_TOKEN_VAULT_PATH`, `GT_NPM_TOKEN_VAULT_FIELD` | `ROUTE` | Gitea Actions variables |
+| `GT_RELEASE_TOKEN_VAULT_PATH`, `GT_RELEASE_TOKEN_VAULT_FIELD` | `ROUTE` | Gitea Actions variables |
+| `GH_MIRROR_TOKEN_VAULT_PATH`, `GH_MIRROR_TOKEN_VAULT_FIELD` | `ROUTE` | Gitea Actions variables |
+| `AIWG_IO_DISPATCH_TOKEN_VAULT_PATH`, `AIWG_IO_DISPATCH_TOKEN_VAULT_FIELD` | `ROUTE` | Gitea Actions variables |
+| `DOCSITE_DEPLOY_KEY_VAULT_PATH`, `DOCSITE_DEPLOY_KEY_VAULT_FIELD` | `ROUTE` | Gitea Actions variables |
+| `RELEASE_SIGNING_KEY_VAULT_PATH`, `RELEASE_SIGNING_KEY_VAULT_FIELD` | `ROUTE` | Gitea Actions variables |
+| `RELEASE_SIGNING_PASSPHRASE_VAULT_PATH`, `RELEASE_SIGNING_PASSPHRASE_VAULT_FIELD` | `ROUTE` | Gitea Actions variables |
+| `VAULT_ADDR` | `ROUTE` | Gitea Actions variable |
+| `DOCSITE_DEPLOY_HOST`, `DOCSITE_DEPLOY_PORT`, `DOCSITE_DEPLOY_USER`, `DOCSITE_DEPLOY_PATH` | `CONFIG` | Gitea Actions variables |
 
-Preview the OpenBao writes:
+The machine-readable variable manifest is
+[`../../ci/vault-migration-plan.json`](../../ci/vault-migration-plan.json).
 
-```bash
-npm run provision:openbao-migration -- --values-dir /path/to/approved/value-files
-```
+## Provisioning
 
-Apply only after confirming the paths and metadata:
+Use the private operations catalog to create the scoped policy and AppRole. Keep
+the concrete policy file outside this repository, then pass it to:
 
 ```bash
-npm run provision:openbao-migration -- --values-dir /path/to/approved/value-files --apply
-```
-
-Policy sketch:
-
-```hcl
-path "kv_internal/data/ci/aiwg/*" {
-  capabilities = ["read"]
-}
-
-path "kv_internal/metadata/ci/aiwg/*" {
-  capabilities = ["read", "list"]
-}
-
-path "kv_internal/data/ci/shared/docs-deploy" {
-  capabilities = ["read"]
-}
-
-path "kv_internal/metadata/ci/shared/docs-deploy" {
-  capabilities = ["read"]
-}
+npm run provision:vault-approle -- --policy-file /path/to/private-policy.hcl
+VAULT_ADMIN_TOKEN=<admin-token> npm run provision:vault-approle -- \
+  --policy-file /path/to/private-policy.hcl \
+  --apply
 ```
 
-Provision the AppRole with short-lived tokens. If the `bao` CLI is unavailable,
-use the checked-in curl-based helper:
+To induct or rotate values from an approved local medium, prepare one file per
+route ID:
 
-```bash
-npm run provision:openbao-approle
-BAO_TOKEN=<admin-token> npm run provision:openbao-approle -- --apply
+```text
+gitea-npm-token.value
+gitea-release-token.value
+github-mirror-token.value
+aiwg-io-dispatch-token.value
+docsite-deploy-key.value
+release-signing-key.value
+release-signing-passphrase.value
 ```
 
-Equivalent `bao` CLI commands:
+Preview the vault writes without printing paths:
 
 ```bash
-bao policy write ci-aiwg ci/openbao-ci-aiwg.hcl
-bao write auth/approle/role/ci-aiwg \
-  token_policies=ci-aiwg \
-  token_ttl=5m \
-  token_max_ttl=15m \
-  secret_id_ttl=0
+npm run provision:vault-migration -- \
+  --routing-env /path/to/private-routing.env \
+  --values-dir /path/to/approved-value-files
 ```
 
-Generate the Gitea bootstrap handoff file without printing values:
+Apply only after confirming the private routing env and value files:
 
 ```bash
-install -d -m 700 ~/.config/openbao/handoff
-umask 077
-{
-  printf 'BAO_CI_ROLE_ID=%s\n' \
-    "$(bao read -field=role_id auth/approle/role/ci-aiwg/role-id)"
-  printf 'BAO_CI_SECRET_ID=%s\n' \
-    "$(bao write -f -field=secret_id auth/approle/role/ci-aiwg/secret-id)"
-} > ~/.config/openbao/handoff/aiwg-ci.env
-chmod 600 ~/.config/openbao/handoff/aiwg-ci.env
-```
-
-Prepare the non-secret deploy variables in a separate env file:
-
-```text
-DEPLOY_HOST=docs-host.example.internal
-DEPLOY_PORT=22
-DEPLOY_USER=deploy
-DEPLOY_PATH=/srv/docs/aiwg
+npm run provision:vault-migration -- \
+  --routing-env /path/to/private-routing.env \
+  --values-dir /path/to/approved-value-files \
+  --apply
 ```
 
-Validate the Gitea handoff without printing values:
+Validate and apply the Gitea handoff without printing values:
 
 ```bash
-npm run configure:gitea-openbao -- \
-  --bootstrap-env ~/.config/openbao/handoff/aiwg-ci.env \
-  --vars-env /path/to/aiwg-deploy-vars.env
-```
-
-Apply after `tea login` is configured for `git.integrolabs.net`:
+npm run configure:gitea-vault -- \
+  --bootstrap-env ~/.config/vault/handoff/aiwg-ci.env \
+  --vars-env /path/to/private-routing-and-deploy.env
 
-```bash
-npm run configure:gitea-openbao -- \
-  --bootstrap-env ~/.config/openbao/handoff/aiwg-ci.env \
-  --vars-env /path/to/aiwg-deploy-vars.env \
+npm run configure:gitea-vault -- \
+  --bootstrap-env ~/.config/vault/handoff/aiwg-ci.env \
+  --vars-env /path/to/private-routing-and-deploy.env \
   --apply
 ```
 
 ## Docsite Deployment Config
 
-The `Docsite Deploy` workflow publishes the AIWG documentation tenant to
-`docs.aiwg.io` over SSH. The private key is fetched from OpenBao. The target
-connection details are non-secret Gitea Actions variables:
-
-| Variable | Purpose |
-|---|---|
-| `DEPLOY_HOST` | Docs host name. |
-| `DEPLOY_PORT` | SSH port. |
-| `DEPLOY_USER` | SSH user. |
-| `DEPLOY_PATH` | Root web path for the AIWG tenant on `docs.aiwg.io`. |
+The `Docsite Deploy` workflow publishes the AIWG documentation tenant over SSH.
+The private key is fetched from vault. Target connection details are Gitea
+Actions variables and should not be hardcoded in workflow files.
 
 `GT_ACCESS_TOKEN` is not used by AIWG's current docsite workflows. The publisher
 is installed from npm as `@pagenary/publisher`; do not add a clone token back to
 the docsite workflows unless the publisher source model changes again.
 
-## Shared `docs.aiwg.io` Tenants
-
-`docs.aiwg.io` is shared with sibling documentation tenants. AIWG owns the root
-tenant at `DEPLOY_PATH`; `roctinam/agentic-sandbox` owns the
-`agentic-sandbox/` subtree and should deploy to:
-
-```text
-${DEPLOY_PATH%/}/agentic-sandbox/
-```
-
-AIWG's root deploy keeps `rsync --delete` enabled, but `docsite-deploy.yml`
-protects registered sibling tenants with rsync receiver-protect filters and a
-dry-run deletion check. Keep the protected-subpath list in
-`.gitea/workflows/docsite-deploy.yml` aligned with the tenant table in
-`.gitea/workflows/README.md`.
-
 ## Troubleshooting
 
-### OpenBao Bootstrap Missing
+### Vault Bootstrap Missing
 
-If `BAO_CI_ROLE_ID` or `BAO_CI_SECRET_ID` is absent, secret-bearing Gitea jobs
+If `VAULT_CI_ROLE_ID` or `VAULT_CI_SECRET_ID` is absent, secret-bearing Gitea jobs
 skip instead of attempting a partial publish. Add or rotate the AppRole
 bootstrap pair in Gitea Actions secrets.
 
 ### Fetch Fails with 403
 
 The `ci-aiwg` AppRole is missing the required path policy or is trying to read
-the wrong leaf. Compare the workflow's spec file with the OpenBao policy and
-verify adjacent paths still deny access.
+the wrong leaf. Compare the workflow spec placeholder names with the private
+vault routing env and policy.
 
 ### Gitea Registry Publish Fails
 
-Check `kv_internal/ci/aiwg/gitea-npm-token` metadata, token scope, and token
-freshness. The value should be a Gitea API token scoped for package publish and
-release API work, but it must remain OpenBao-only.
+Check the private routing entry, token scope, and token freshness. The value
+must remain vault-only.