@stravica-ai/digital-operator-pa 0.1.31 → 0.1.33

package/dist/engineering-pa-cli/docs/gsc.md

@@ -52,34 +52,34 @@ Two npm packages (declared in `@stravica-ai/digital-operator-pa`):
    single-file vault. Store the key in the pot the host is already
    configured to read; no `pa gsc`-specific configuration is needed.
 
-6. **Store Cloudflare credentials** (also one-time). Two key shapes are
-   supported; pick whichever fits your setup:
+6. **Store Cloudflare credentials** (also one-time). Each CF account is
+   addressed by a suffixed vault-key pair. `--account <name>` is required
+   on every invocation — the unsuffixed bare pair that used to be a
+   single-account default was dropped in the 2026-09-01 rename
+   (`w-2026-08-31-dave-010`).
 
-   **Single-account setup** — one CF account, no `--account` flag needed:
-   ```bash
-   pnpm exec secrets set CLOUDFLARE_PAGES_API_KEY <token>
-   pnpm exec secrets set CLOUDFLARE_PAGES_ACCOUNT_ID <account-id>
-   ```
+   Pick the surface segment that matches how the token is actually
+   scoped in Cloudflare:
 
-   **Multi-account setup** — multiple CF accounts, each addressed by name:
    ```bash
-   # Stravica account → addressed as --account stravica
-   pnpm exec secrets set CLOUDFLARE_PAGES_API_KEY_STRAVICA <token>
-   pnpm exec secrets set CLOUDFLARE_PAGES_ACCOUNT_ID_STRAVICA <account-id>
+   # Stravica account (Workers Scripts + D1) → --account stravica
+   pnpm exec secrets set CLOUDFLARE_WORKERS_API_TOKEN_STRAVICA <token>
+   pnpm exec secrets set CLOUDFLARE_WORKERS_ACCOUNT_ID_STRAVICA <account-id>
 
-   # Clive account → addressed as --account clive
-   pnpm exec secrets set CLOUDFLARE_PAGES_API_KEY_CLIVE <token>
+   # Clive account (Pages + zone purge) → --account clive
+   pnpm exec secrets set CLOUDFLARE_PAGES_API_TOKEN_CLIVE <token>
    pnpm exec secrets set CLOUDFLARE_PAGES_ACCOUNT_ID_CLIVE <account-id>
    ```
 
-   The CF API token needs `Zone:DNS:Edit` and `Zone:Zone:Read` for any
-   zones the tool will operate on. Account-level "Write to all resources"
-   tokens also work.
+   The CF API token needs the permissions its surface implies (for DNS
+   planting: `Zone:DNS:Edit` and `Zone:Zone:Read` on the target zones;
+   account-level "Write to all resources" tokens also work).
 
-   For back-compat, the legacy `CLOUDFLARE_API_TOKEN` /
-   `CLOUDFLARE_ACCOUNT_ID` pair is read as a last-resort fallback when
-   no `--account` flag is passed and the `CLOUDFLARE_PAGES_*` unsuffixed
-   pair is absent. Don't rely on it — set the `CLOUDFLARE_PAGES_*` keys.
+   For back-compat, the deprecated `CLOUDFLARE_PAGES_API_KEY_<NAME>` /
+   `CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>` pair is still accepted, and a
+   hit emits a stderr deprecation warning naming the current pair. Rename
+   the vault entries at your convenience — the deprecated pair will be
+   removed in a follow-up.
 
    Same scoped-vault note as the SA key: on scoped hosts these live in
    whichever pot `secrets get` reads (see step 5); use `secrets set --scope
@@ -134,26 +134,38 @@ pnpm exec pa gsc list-properties
 
 ## Multi-account selection
 
-When `--account <name>` is passed to `verify-via-cf-dns`, the tool resolves
-the Cloudflare credentials by upper-casing the name and looking up the
-corresponding suffixed vault pair. For example:
+`--account <name>` is required on every invocation. The tool upper-cases
+the name and tries the candidate vault-key pairs below in order — the
+first fully-present pair wins. Storing multiple pairs for the same
+account is a supported migration state; the tool always picks the
+highest-priority pair that resolves.
 
 ```
---account stravica  ->  CLOUDFLARE_PAGES_API_KEY_STRAVICA
-                        CLOUDFLARE_PAGES_ACCOUNT_ID_STRAVICA
---account clive     ->  CLOUDFLARE_PAGES_API_KEY_CLIVE
-                        CLOUDFLARE_PAGES_ACCOUNT_ID_CLIVE
+1.  CLOUDFLARE_WORKERS_API_TOKEN_<NAME>
+    CLOUDFLARE_WORKERS_ACCOUNT_ID_<NAME>
+    Workers surface — Workers Scripts, D1, KV. Used by --account stravica.
+
+2.  CLOUDFLARE_PAGES_API_TOKEN_<NAME>
+    CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
+    Pages surface — Pages + zone purge. Used by --account clive.
+
+3.  CLOUDFLARE_PAGES_API_KEY_<NAME>
+    CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
+    Deprecated pre-2026-09-01 naming. Accepted with a stderr warning;
+    will be removed in a follow-up. Rename the vault entries at your
+    convenience.
 ```
 
-If `--account` is passed but the suffixed pair isn't set, the command
-fails fast with a message telling you which key is missing. It does
-**not** silently fall back to the unsuffixed pair — that would defeat
-the safety the flag exists to provide.
+If `--account` is passed but none of the candidate pairs are fully set,
+the command fails fast with a message naming the primary (WORKERS) pair
+you're expected to store. It never silently falls back to any pair not
+addressed by the suffix — that would defeat the safety the flag exists
+to provide.
 
-Without `--account`, resolution order is:
-1. `CLOUDFLARE_PAGES_API_KEY` + `CLOUDFLARE_PAGES_ACCOUNT_ID`
-2. Legacy `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` (back-compat
-   only; do not rely on this).
+The unsuffixed bare pair (`CLOUDFLARE_PAGES_API_KEY` /
+`CLOUDFLARE_PAGES_ACCOUNT_ID`) and the very-legacy
+`CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` pair are no longer
+read — `--account <name>` is mandatory.
 
 The account name accepts letters and digits only — anything else is a
 usage error.

package/dist/engineering-pa-cli/docs/staging-alias.md

@@ -98,8 +98,11 @@ Edit `src/staging-alias/sites.mjs`. Add one entry:
 },
 ```
 
-…and store the vault keys: `CLOUDFLARE_PAGES_API_KEY_NEWSITE` +
-`CLOUDFLARE_PAGES_ACCOUNT_ID_NEWSITE`.
+…and store the vault keys under the surface segment that matches how
+the token is scoped: `CLOUDFLARE_WORKERS_API_TOKEN_NEWSITE` +
+`CLOUDFLARE_WORKERS_ACCOUNT_ID_NEWSITE` (Workers surface), or
+`CLOUDFLARE_PAGES_API_TOKEN_NEWSITE` + `CLOUDFLARE_PAGES_ACCOUNT_ID_NEWSITE`
+(Pages surface). See `packages/cli/docs/gsc.md` for the candidate order.
 
 ## Exit codes
 

package/dist/engineering-pa-cli/src/gsc/cli.mjs

@@ -53,14 +53,19 @@ Auth (one-time setup; see docs/gsc.md):
     GSC_SERVICE_ACCOUNT_KEY (entire JSON contents as the value).
   - SA email added as a user on each GSC property via the GSC dashboard.
 
-Cloudflare DNS planting reads two vault keys. Resolution order:
-  1. With --account <name>: CLOUDFLARE_PAGES_API_KEY_<NAME> +
-                            CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
-                            (e.g. --account stravica -> *_STRAVICA pair)
-  2. Without --account:     CLOUDFLARE_PAGES_API_KEY +
-                            CLOUDFLARE_PAGES_ACCOUNT_ID
-  3. Legacy fallback:       CLOUDFLARE_API_TOKEN +
-                            CLOUDFLARE_ACCOUNT_ID
+Cloudflare DNS planting reads two vault keys. --account <name> is
+required (letters/digits only). The suffix is upper-cased and each
+candidate pair below is tried in order — first fully-present pair wins.
+
+  1. CLOUDFLARE_WORKERS_API_TOKEN_<NAME> +
+     CLOUDFLARE_WORKERS_ACCOUNT_ID_<NAME>
+     (Workers surface — e.g. --account stravica)
+  2. CLOUDFLARE_PAGES_API_TOKEN_<NAME> +
+     CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
+     (Pages surface — e.g. --account clive)
+  3. CLOUDFLARE_PAGES_API_KEY_<NAME> +
+     CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
+     (deprecated pre-2026-09-01 naming; hit emits a stderr warning)
 `;
 
 export async function run(argv, overrides = {}) {

package/dist/engineering-pa-cli/src/gsc/cloudflare.mjs

@@ -5,22 +5,29 @@
 //   2. find an existing TXT record by name (idempotency)
 //   3. create or update a TXT record
 //
-// Credentials are read from the SOPS vault. The vault holds two key
-// shapes for Cloudflare:
+// Credentials are read from the SOPS vault. The vault holds account-suffixed
+// pairs — the caller picks the suffix via the `account` option (lower-cased
+// externally; matched case-insensitively to the upper-case suffix).
 //
-//   - Account-suffixed pair (preferred — multi-account safe):
-//       CLOUDFLARE_PAGES_API_KEY_<SUFFIX>
-//       CLOUDFLARE_PAGES_ACCOUNT_ID_<SUFFIX>
-//     The caller picks the suffix via the `account` option (lower-cased
-//     externally; matched case-insensitively to the upper-case suffix).
+// Vault-key shapes tried in order per account (2026-09-01 rename,
+// w-2026-08-31-dave-010; see vault-key-rename-plan-2026-08-31.md):
 //
-//   - Unsuffixed pair (single-account default):
-//       CLOUDFLARE_PAGES_API_KEY
-//       CLOUDFLARE_PAGES_ACCOUNT_ID
+//   1. Workers surface (Workers Scripts / D1 / KV) — e.g. Stravica:
+//        CLOUDFLARE_WORKERS_API_TOKEN_<SUFFIX>
+//        CLOUDFLARE_WORKERS_ACCOUNT_ID_<SUFFIX>
 //
-//   - Legacy bare pair (back-compat fallback):
-//       CLOUDFLARE_API_TOKEN
-//       CLOUDFLARE_ACCOUNT_ID
+//   2. Pages surface (Pages + zone purge) — e.g. Clive:
+//        CLOUDFLARE_PAGES_API_TOKEN_<SUFFIX>
+//        CLOUDFLARE_PAGES_ACCOUNT_ID_<SUFFIX>
+//
+//   3. Deprecated (pre-2026-09-01) — accepted with a stderr warning during
+//      the transition window; will be removed in a follow-up:
+//        CLOUDFLARE_PAGES_API_KEY_<SUFFIX>
+//        CLOUDFLARE_PAGES_ACCOUNT_ID_<SUFFIX>
+//
+// The unsuffixed bare pair (CLOUDFLARE_PAGES_API_KEY / CLOUDFLARE_PAGES_
+// ACCOUNT_ID) that used to be accepted as a single-account default was
+// removed in this same rename — `--account <name>` is now required.
 //
 // `fetchImpl` and `now` are injectable for tests.
 
@@ -28,18 +35,23 @@ import { resolveCommandPaths, checkVault, secretsFileExists, sopsDecrypt, VaultE
 
 const CF_API = 'https://api.cloudflare.com/client/v4';
 
-// Vault-key shapes. `*_TEMPLATE` uses `<S>` as the suffix placeholder.
-const VAULT_KEYS = Object.freeze({
-  // Account-suffixed (preferred).
-  tokenTemplate: 'CLOUDFLARE_PAGES_API_KEY_<S>',
-  accountIdTemplate: 'CLOUDFLARE_PAGES_ACCOUNT_ID_<S>',
-  // Unsuffixed (single-account default).
-  tokenUnsuffixed: 'CLOUDFLARE_PAGES_API_KEY',
-  accountIdUnsuffixed: 'CLOUDFLARE_PAGES_ACCOUNT_ID',
-  // Legacy bare (back-compat fallback).
-  tokenLegacy: 'CLOUDFLARE_API_TOKEN',
-  accountIdLegacy: 'CLOUDFLARE_ACCOUNT_ID',
-});
+// Ordered candidate templates. First fully-present pair wins per account.
+// The `deprecated` flag drives the stderr warning + return-value flag.
+const CANDIDATE_TEMPLATES = Object.freeze([
+  Object.freeze({
+    tokenTemplate: 'CLOUDFLARE_WORKERS_API_TOKEN_<S>',
+    accountIdTemplate: 'CLOUDFLARE_WORKERS_ACCOUNT_ID_<S>',
+  }),
+  Object.freeze({
+    tokenTemplate: 'CLOUDFLARE_PAGES_API_TOKEN_<S>',
+    accountIdTemplate: 'CLOUDFLARE_PAGES_ACCOUNT_ID_<S>',
+  }),
+  Object.freeze({
+    tokenTemplate: 'CLOUDFLARE_PAGES_API_KEY_<S>',
+    accountIdTemplate: 'CLOUDFLARE_PAGES_ACCOUNT_ID_<S>',
+    deprecated: true,
+  }),
+]);
 
 /**
  * Normalise an `--account` value to the upper-case suffix used in the
@@ -65,28 +77,32 @@ export function accountSuffix(account) {
 }
 
 /**
- * Build the vault key names a given `account` selection resolves to.
- * If `account` is omitted, returns the unsuffixed pair (with a legacy
- * fallback list for back-compat).
+ * Build the ordered list of vault-key candidate pairs a given `account`
+ * selection resolves to. Callers try candidates in order — first fully-
+ * present pair wins.
  *
- * @param {string} [account]
- * @returns {{ tokenKey: string, accountIdKey: string, fallbacks?: Array<{tokenKey: string, accountIdKey: string}> }}
+ * @param {string} account   Required — the unsuffixed bare pair was dropped
+ *                           in the 2026-09-01 rename (w-2026-08-31-dave-010).
+ * @returns {{ candidates: Array<{tokenKey: string, accountIdKey: string, deprecated?: boolean}> }}
  */
 export function resolveVaultKeys(account) {
-  if (account) {
-    const s = accountSuffix(account);
-    return {
-      tokenKey: VAULT_KEYS.tokenTemplate.replace('<S>', s),
-      accountIdKey: VAULT_KEYS.accountIdTemplate.replace('<S>', s),
-    };
+  if (!account) {
+    throw new VaultError(
+      '--account <name> is required (e.g. --account stravica). ' +
+      'The unsuffixed vault-key fallback was removed in the 2026-09-01 rename.',
+      1,
+    );
   }
-  return {
-    tokenKey: VAULT_KEYS.tokenUnsuffixed,
-    accountIdKey: VAULT_KEYS.accountIdUnsuffixed,
-    fallbacks: [
-      { tokenKey: VAULT_KEYS.tokenLegacy, accountIdKey: VAULT_KEYS.accountIdLegacy },
-    ],
-  };
+  const s = accountSuffix(account);
+  const candidates = CANDIDATE_TEMPLATES.map((tpl) => {
+    const entry = {
+      tokenKey: tpl.tokenTemplate.replace('<S>', s),
+      accountIdKey: tpl.accountIdTemplate.replace('<S>', s),
+    };
+    if (tpl.deprecated) entry.deprecated = true;
+    return entry;
+  });
+  return { candidates };
 }
 
 /**
@@ -95,19 +111,18 @@ export function resolveVaultKeys(account) {
  *
  * Resolution order:
  *   1. Test overrides (`cloudflareToken` + `cloudflareAccountId`).
- *   2. If `account` provided: only the suffixed pair, hard-fail if missing.
- *   3. Otherwise: unsuffixed pair, then the legacy bare pair as fallback.
+ *   2. `--account` is required. Try each candidate pair in order; first
+ *      fully-present pair wins. A hit on a deprecated pair emits a
+ *      stderr warning (unless `warn` is overridden for tests).
  *
  * @param {object} overrides
  * @param {object} [overrides.paths]
  * @param {string} [overrides.cloudflareToken]
  * @param {string} [overrides.cloudflareAccountId]
- * @param {string} [overrides.account]            Account selector (e.g. "stravica").
+ * @param {string} [overrides.account]            Account selector (e.g. "stravica"). Required unless raw creds supplied.
  * @param {object} [overrides.vaultData]          Pre-decrypted vault map (test seam).
- *        When provided, the function uses this instead of running the SOPS
- *        check + decrypt. Lets tests cover the suffix-resolution and
- *        fallback paths without touching the filesystem.
- * @returns {Promise<{token: string, accountId: string, account: string|null, vaultKeys: {tokenKey: string, accountIdKey: string}}>}
+ * @param {Function} [overrides.warn]             Test seam for the deprecation warning (defaults to writing to stderr).
+ * @returns {Promise<{token: string, accountId: string, account: string|null, vaultKeys: {tokenKey: string, accountIdKey: string, deprecated?: boolean}}>}
  */
 export async function loadCloudflareCreds(overrides = {}) {
   if (overrides.cloudflareToken && overrides.cloudflareAccountId) {
@@ -118,6 +133,9 @@ export async function loadCloudflareCreds(overrides = {}) {
       vaultKeys: null,
     };
   }
+
+  const plan = resolveVaultKeys(overrides.account);
+
   let data;
   if (overrides.vaultData) {
     data = overrides.vaultData;
@@ -143,50 +161,33 @@ export async function loadCloudflareCreds(overrides = {}) {
     data = await sopsDecrypt(paths, paths.secretsFile);
   }
 
-  const plan = resolveVaultKeys(overrides.account);
+  const warn = overrides.warn || ((msg) => process.stderr.write(`${msg}\n`));
 
-  // Account-suffixed: must hit exactly the suffixed pair.
-  if (overrides.account) {
-    const token = data[plan.tokenKey];
-    const accountId = data[plan.accountIdKey];
-    if (!token || !accountId) {
-      const missing = [];
-      if (!token) missing.push(plan.tokenKey);
-      if (!accountId) missing.push(plan.accountIdKey);
-      throw new VaultError(
-        `--account "${overrides.account}" expects vault keys [${missing.join(', ')}] but they are not set. ` +
-        `Store them with:\n  secrets set ${plan.tokenKey} <token>\n  secrets set ${plan.accountIdKey} <id>`,
-        1,
-      );
-    }
-    return {
-      token,
-      accountId,
-      account: overrides.account,
-      vaultKeys: { tokenKey: plan.tokenKey, accountIdKey: plan.accountIdKey },
-    };
-  }
-
-  // No --account: try unsuffixed pair first, then legacy bare pair.
-  const candidates = [
-    { tokenKey: plan.tokenKey, accountIdKey: plan.accountIdKey },
-    ...(plan.fallbacks || []),
-  ];
-  for (const cand of candidates) {
+  for (const cand of plan.candidates) {
     const token = data[cand.tokenKey];
     const accountId = data[cand.accountIdKey];
     if (token && accountId) {
-      return { token, accountId, account: null, vaultKeys: cand };
+      if (cand.deprecated) {
+        warn(
+          `warning: Cloudflare vault keys [${cand.tokenKey}, ${cand.accountIdKey}] are deprecated ` +
+          `(pre-2026-09-01 naming). Rename to the current pair — see ` +
+          `packages/cli/docs/gsc.md for the current key shapes.`,
+        );
+      }
+      return {
+        token,
+        accountId,
+        account: overrides.account,
+        vaultKeys: { ...cand },
+      };
     }
   }
-  // None matched — error message lists the primary pair the operator
-  // is expected to set; legacy fallback is a back-compat courtesy, not
-  // a thing we advertise.
+
+  const primary = plan.candidates[0];
   throw new VaultError(
-    `Cloudflare vault keys not found. Pass --account <name> (e.g. --account stravica) ` +
-    `to use the per-account pair, or store the default pair:\n` +
-    `  secrets set ${VAULT_KEYS.tokenUnsuffixed} <token>\n` +
-    `  secrets set ${VAULT_KEYS.accountIdUnsuffixed} <id>`,
+    `--account "${overrides.account}" expects vault keys [${primary.tokenKey}, ${primary.accountIdKey}] ` +
+    `(or one of the fallback pairs listed in packages/cli/docs/gsc.md) but none are set. ` +
+    `Store them with:\n  secrets set ${primary.tokenKey} <token>\n  secrets set ${primary.accountIdKey} <id>`,
     1,
   );
 }

package/dist/engineering-pa-cli/src/knowledge/graph.mjs

@@ -26,6 +26,7 @@
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
+import { resolveExtraScanRoots } from '../../../engineering-pa-core/src/knowledge/retrieval/links.mjs';
 
 const GRAPH_RELATIVE_PATH = 'operator/knowledge/.graph.json';
 
@@ -637,15 +638,25 @@ function guidedMissHint(graph, term) {
 async function readBody(repoRoot, id) {
   // The id is either a path relative to the repo root, or a bare slug.
   // We try repoRoot/<id> first, then repoRoot/operator/knowledge/<id>.
-  const candidates = [
-    resolve(repoRoot, id),
-    resolve(repoRoot, 'operator', 'knowledge', id),
-  ];
-  for (const path of candidates) {
-    if (existsSync(path)) {
-      try {
-        return await readFile(path, 'utf8');
-      } catch { return null; }
+  //
+  // Extra scan roots (Wave H, w-2026-08-24-dave-033): a doc merged into the
+  // graph from a pull-clone at `~/stravica-library-clones/<tier>/` has an id
+  // shaped `operator/knowledge/<domain>/<file>.md` but is not resolvable
+  // under the home repoRoot. The extra scan roots — same env var the
+  // builders read — are checked in declared order after the home root, so
+  // `--full` body search still finds the file.
+  const roots = [repoRoot, ...resolveExtraScanRoots()];
+  for (const root of roots) {
+    const candidates = [
+      resolve(root, id),
+      resolve(root, 'operator', 'knowledge', id),
+    ];
+    for (const path of candidates) {
+      if (existsSync(path)) {
+        try {
+          return await readFile(path, 'utf8');
+        } catch { return null; }
+      }
     }
   }
   return null;

package/dist/engineering-pa-cli/src/staging-alias/sites.mjs

@@ -16,8 +16,10 @@
 //
 // `accountKey` is the vault-key suffix (lowercase form passed to
 // `loadCloudflareCreds({ account })`). The CF helper upper-cases it
-// internally to build `CLOUDFLARE_PAGES_API_KEY_<SUFFIX>` + matching
-// account-id key.
+// internally and tries the current candidate templates in order —
+// CLOUDFLARE_WORKERS_API_TOKEN_<SUFFIX>, then CLOUDFLARE_PAGES_API_
+// TOKEN_<SUFFIX>, then the deprecated CLOUDFLARE_PAGES_API_KEY_<SUFFIX>
+// (see cloudflare.mjs for the full list and gsc.md for the rationale).
 
 /** @typedef {{
  *   hostname: string,

package/dist/engineering-pa-core/src/knowledge/retrieval/backlink-indexer.mjs

@@ -27,7 +27,7 @@ import { readFile } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { join, resolve, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { buildFileIndex, extractLinks, scanDirsFor, toPosix, walkFiles } from './links.mjs';
+import { buildFileIndex, extractLinks, scanSourcesFor, toPosix, walkFiles } from './links.mjs';
 import { writeJsonAtomic } from './write-atomic.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -64,23 +64,35 @@ Output: operator/knowledge/.backlinks.json
  *   writes a minimal one. Readers treat it as optional either way.
  * @returns {Promise<{outPath:string, targetCount:number, unresolved:object[]}>}
  */
-export async function buildBacklinkIndex({ root, coverage = null }) {
+export async function buildBacklinkIndex({ root, coverage = null, extraRoots }) {
   // Pass 1 — enumerate. `[[slug]]` cannot be resolved without knowing which
   // files exist, so the whole tree is collected before any link is read.
-  const allFiles = [];
-  for (const dir of scanDirsFor(root)) {
-    allFiles.push(...await walkFiles(dir));
+  //
+  // Sources: home root first, then env-supplied extra scan roots (Wave H,
+  // w-2026-08-24-dave-033). Files are relativised against THEIR source root
+  // so ids are shape-compatible across the flat namespace. Home-wins on
+  // collision.
+  const sources = scanSourcesFor(root, { extraRoots });
+  const fileEntries = [];
+  const seenIds = new Set();
+  for (const { sourceRoot, scanDirs } of sources) {
+    for (const dir of scanDirs) {
+      for (const abs of await walkFiles(dir)) {
+        const id = toPosix(relative(sourceRoot, abs));
+        if (seenIds.has(id)) continue;
+        seenIds.add(id);
+        fileEntries.push({ abs, id });
+      }
+    }
   }
-  const fileIds = allFiles.map((f) => toPosix(relative(root, f)));
-  const fileIndex = buildFileIndex(fileIds);
+  const fileIndex = buildFileIndex(fileEntries.map((e) => e.id));
 
   // Pass 2 — build backlinks map: target -> [sources]
   const backlinks = {};
   const unresolved = [];
 
-  for (let i = 0; i < allFiles.length; i++) {
-    const content = await readFile(allFiles[i], 'utf8');
-    const relSource = fileIds[i];
+  for (const { abs, id: relSource } of fileEntries) {
+    const content = await readFile(abs, 'utf8');
     const result = extractLinks(content, relSource, fileIndex);
     unresolved.push(...result.unresolved);
 

package/dist/engineering-pa-core/src/knowledge/retrieval/graph-builder.mjs

@@ -24,7 +24,7 @@ import {
   deriveDomain,
   extractLinks,
   isIndexJson,
-  scanDirsFor,
+  scanSourcesFor,
   toPosix,
   walkFiles,
 } from './links.mjs';
@@ -87,20 +87,38 @@ function reportUnresolved(label, entries) {
  * @returns {Promise<object>}  outPath, counts, diagnostics and the unresolved
  *   entries the CLI reports
  */
-export async function buildKnowledgeGraph({ root, coverage = null }) {
-  const scanDirs = scanDirsFor(root);
+export async function buildKnowledgeGraph({ root, coverage = null, extraRoots }) {
+  // Sources: home root first, then each extra scan root (env-supplied by
+  // default). Files from an extra root are relativised against THEIR root,
+  // so their ids are still shaped `operator/knowledge/…` and merge into the
+  // same flat namespace as home. Home wins on collision (first-in policy).
+  const sources = scanSourcesFor(root, { extraRoots });
 
   // ── Pass 1: enumerate the tree ────────────────────────────────────────
   // Resolution needs the whole file set before any link is interpreted —
   // `[[slug]]` cannot be resolved without knowing which files exist.
-  const allFiles = [];
-  const indexPaths = [];
-  for (const dir of scanDirs) {
-    allFiles.push(...await walkFiles(dir));
-    indexPaths.push(...await walkFiles(dir, isIndexJson));
+  //
+  // Each entry pairs the on-disk path with the source root it belongs to,
+  // so pass 2 can read the file from disk while emitting a source-relative
+  // id. Ids that collide keep the first occurrence (home-wins).
+  const fileEntries = [];
+  const indexEntries = [];
+  const seenIds = new Set();
+  for (const { sourceRoot, scanDirs } of sources) {
+    for (const dir of scanDirs) {
+      for (const abs of await walkFiles(dir)) {
+        const id = toPosix(relative(sourceRoot, abs));
+        if (seenIds.has(id)) continue;
+        seenIds.add(id);
+        fileEntries.push({ abs, id });
+      }
+      for (const abs of await walkFiles(dir, isIndexJson)) {
+        const id = toPosix(relative(sourceRoot, abs));
+        indexEntries.push({ abs, id });
+      }
+    }
   }
-  const fileIds = allFiles.map((f) => toPosix(relative(root, f)));
-  const fileIndex = buildFileIndex(fileIds);
+  const fileIndex = buildFileIndex(fileEntries.map((e) => e.id));
 
   // ── Pass 2: nodes + forward edges ─────────────────────────────────────
   const nodesMap = new Map();
@@ -115,10 +133,8 @@ export async function buildKnowledgeGraph({ root, coverage = null }) {
     edges.push({ from, to, type });
   };
 
-  for (let i = 0; i < allFiles.length; i++) {
-    const filePath = allFiles[i];
-    const relPath = fileIds[i];
-    const content = await readFile(filePath, 'utf8');
+  for (const { abs, id: relPath } of fileEntries) {
+    const content = await readFile(abs, 'utf8');
     const title = extractTitle(content) || relPath.split('/').pop().replace('.md', '');
 
     nodesMap.set(relPath, { id: relPath, title, domain: deriveDomain(relPath) });
@@ -130,8 +146,7 @@ export async function buildKnowledgeGraph({ root, coverage = null }) {
 
   // ── index.json hubs ───────────────────────────────────────────────────
   const indexFiles = [];
-  for (const indexPath of indexPaths) {
-    const id = toPosix(relative(root, indexPath));
+  for (const { abs: indexPath, id } of indexEntries) {
     let data;
     try {
       data = JSON.parse(await readFile(indexPath, 'utf8'));
@@ -180,7 +195,7 @@ export async function buildKnowledgeGraph({ root, coverage = null }) {
     version: '1.0',
     generatedAt: new Date().toISOString(),
     diagnostics: {
-      markdownFiles: allFiles.length,
+      markdownFiles: fileEntries.length,
       indexHubs: {
         files: indexFiles.length,
         entries: hubs.entryCount,

package/dist/engineering-pa-core/src/knowledge/retrieval/links.mjs

@@ -39,6 +39,50 @@ import { join, normalize, posix } from 'node:path';
 // Knowledge trees the builders scan, repo-root-relative.
 export const KNOWLEDGE_SCAN_DIRS = ['operator/knowledge', 'core/knowledge'];
 
+// Environment variable that names ADDITIONAL scan roots beyond the workspace
+// root. Colon-separated absolute paths, each pointing at a directory shaped
+// like a workspace root (i.e. containing an `operator/knowledge/` subtree).
+//
+// Motivation (Wave H, w-2026-08-24-dave-033): the REMOTE-mode read path is
+// `~/stravica-library-clones/<tier>/`. Each tier repo carries its own
+// `operator/knowledge/**` tree, and canonical knowledge lives in those tier
+// repos — not in the home workspace. Without extra scan roots, `pa knowledge`
+// on an operator host misses every canonical doc. Extra roots let the builders
+// merge tier-repo content into the SAME graph the home tree produces, so node
+// ids are still `operator/knowledge/<domain>/<file>.md` regardless of which
+// root supplied the file.
+//
+// Collision policy: FIRST WINS. The home workspace root is scanned first, so
+// a doc present in both home and a tier clone keeps the home copy. This
+// matches the retirement's repatriation rule ("HOME-REPO copy wins for
+// estate-native classes"); the intent is that canonical docs only ever live
+// on ONE side, and any collision is a symptom that needs resolving upstream.
+export const EXTRA_SCAN_ROOTS_ENV = 'LIBRARY_KNOWLEDGE_EXTRA_ROOTS';
+
+/**
+ * Read + normalise the extra scan roots from the environment. Returns an
+ * array of absolute paths (deduped, in declared order). Missing / empty
+ * entries are silently skipped so a stray colon never manufactures a bogus
+ * root.
+ *
+ * @param {NodeJS.ProcessEnv} [env] defaults to process.env
+ * @returns {string[]}
+ */
+export function resolveExtraScanRoots(env = process.env) {
+  const raw = env[EXTRA_SCAN_ROOTS_ENV];
+  if (typeof raw !== 'string' || raw.trim() === '') return [];
+  const seen = new Set();
+  const out = [];
+  for (const part of raw.split(':')) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    if (seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    out.push(trimmed);
+  }
+  return out;
+}
+
 const WIKI_RE = /\[\[([^\]]+)\]\]/g;
 const MD_LINK_RE = /\[([^\]]*)\]\(([^)]+)\)/g;
 const EXTERNAL_RE = /^(?:https?:\/\/|mailto:|#)/;
@@ -120,6 +164,31 @@ export function scanDirsFor(root) {
   return KNOWLEDGE_SCAN_DIRS.map((rel) => join(root, ...rel.split('/')));
 }
 
+/**
+ * Full scan-source list: the home workspace root first, then every extra
+ * scan root from the environment. Each entry pairs a source root with the
+ * scan dirs it contributes, so callers relativise ids against the SOURCE
+ * root (yielding `operator/knowledge/…` shaped ids regardless of where on
+ * disk the file lives).
+ *
+ * Home comes first so the first-wins collision policy resolves in favour
+ * of the home workspace copy.
+ *
+ * @param {string} root the home workspace root
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] defaults to process.env
+ * @param {string[]} [opts.extraRoots] override the env-resolved list (tests)
+ * @returns {{ sourceRoot: string, scanDirs: string[] }[]}
+ */
+export function scanSourcesFor(root, opts = {}) {
+  const extras = opts.extraRoots ?? resolveExtraScanRoots(opts.env);
+  const sources = [{ sourceRoot: root, scanDirs: scanDirsFor(root) }];
+  for (const extra of extras) {
+    sources.push({ sourceRoot: extra, scanDirs: scanDirsFor(extra) });
+  }
+  return sources;
+}
+
 // ── File index ──────────────────────────────────────────────────────────────
 
 function pushInto(map, key, value) {

package/dist/engineering-pa-library-cli/src/cli.mjs

@@ -18,6 +18,7 @@ import { runFlush } from './verbs/flush.mjs';
 import { runGet } from './verbs/get.mjs';
 import { runSearch } from './verbs/search.mjs';
 import { runStatus } from './verbs/status.mjs';
+import { runRefreshClones } from './verbs/refresh-clones.mjs';
 
 const USAGE = `library — REMOTE-mode client for the remote-library service.
 
@@ -27,6 +28,7 @@ Usage:
   library get <path>
   library search <query> [--files-only]
   library status [--json]
+  library refresh-clones [--json] [--timeout-ms <n>] [--tier <name>]...
   library -h | --help
 
 Reads config from operator/config/preferences.json (+ preferences.local.json overlay).
@@ -86,6 +88,7 @@ export async function main(argv, seams = {}) {
       case 'get':      return await runGet({ ...ctx, args: parseGet(rest) });
       case 'search':   return await runSearch({ ...ctx, args: parseSearch(rest) });
       case 'status':   return await runStatus({ ...ctx, args: parseStatus(rest) });
+      case 'refresh-clones': return await runRefreshClones({ ...ctx, args: parseRefreshClones(rest) });
       default:
         err(`[library] unknown verb: ${verb}`);
         log(USAGE);
@@ -140,3 +143,17 @@ function parseStatus(argv) {
   });
   return { json: values.json };
 }
+function parseRefreshClones(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: false,
+    options: {
+      json:         { type: 'boolean', default: false },
+      'timeout-ms': { type: 'string' },
+      tier:         { type: 'string', multiple: true },
+    },
+  });
+  const timeoutMs = values['timeout-ms'] ? parseInt(values['timeout-ms'], 10) : undefined;
+  return { json: values.json, timeoutMs, tiers: values.tier };
+}

package/dist/engineering-pa-library-cli/src/verbs/refresh-clones.mjs

@@ -0,0 +1,153 @@
+// verbs/refresh-clones.mjs — `library refresh-clones`
+//
+// REMOTE-mode session-boot verb: refreshes every tier clone under the
+// pull-clones root by running `git fetch --quiet origin` then
+// `git pull --ff-only --quiet origin main` for each. Called from the
+// session-boot hook (Wave H, w-2026-08-24-dave-033) so `pa knowledge`
+// reads the freshest projection of the tier repos.
+//
+// Design notes:
+//   - Q4 boot-only refresh: this verb is meant to be invoked from the
+//     session-boot path (Claude Code SessionStart hook, `pa environment`
+//     adjacency). It is NOT a cron / launchd job — the retirement plan
+//     is boot-only refresh v1.
+//   - Parallel per tier. Total wall time is dominated by the slowest
+//     tier's fetch; per-tier timeout keeps a wedged remote from
+//     blocking session start.
+//   - Refuses to touch a tier clone with uncommitted local changes
+//     (`git status --porcelain` non-empty) — pull-clones are a
+//     read-only projection per spec §3.3 and any local edit is a
+//     corruption signal, not a merge target.
+//   - Exit code 0 iff every tier refreshed successfully. Any per-tier
+//     failure surfaces on stderr and produces a non-zero exit so the
+//     session-boot hook logs it.
+
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { pullClonesRootExists, resolvePullClonesRoot } from '../pull-clones.mjs';
+
+const DEFAULT_TIER_TIMEOUT_MS = 20_000;
+
+/**
+ * @param {object} ctx
+ * @param {object} ctx.config
+ * @param {object} [ctx.args]                 { json?, timeoutMs?, tiers? }
+ * @param {(...m:unknown[])=>void} [ctx.log]
+ * @param {(...m:unknown[])=>void} [ctx.err]
+ * @param {(args:string[], cwd:string, opts?:object)=>Promise<{code:number, stdout:string, stderr:string}>} [ctx.git]
+ * @returns {Promise<number>}
+ */
+export async function runRefreshClones({
+  config,
+  args = {},
+  log = defaultLog,
+  err = defaultErr,
+  git = runGit,
+}) {
+  const root = resolvePullClonesRoot({ preferences: config.preferences });
+  const timeoutMs = args.timeoutMs ?? DEFAULT_TIER_TIMEOUT_MS;
+
+  if (!pullClonesRootExists(root)) {
+    const payload = { root, tiers: [], error: 'pull-clones root not found' };
+    if (args.json) log(JSON.stringify(payload, null, 2));
+    else err(`[library refresh-clones] pull-clones root not found: ${root}`);
+    return 2;
+  }
+
+  const tiers = await enumerateTiers(root, args.tiers);
+  const results = await Promise.all(
+    tiers.map((tier) => refreshOne({ tier, git, timeoutMs })),
+  );
+
+  const failures = results.filter((r) => r.status !== 'ok');
+  const payload = { root, tiers: results, ok: failures.length === 0 };
+
+  if (args.json) {
+    log(JSON.stringify(payload, null, 2));
+  } else {
+    log(`pull-clones root: ${root} (${results.length} tier${results.length === 1 ? '' : 's'})`);
+    for (const r of results) {
+      const line = r.status === 'ok'
+        ? `  ${r.name.padEnd(32)} ok (${r.newCommits} new commit${r.newCommits === 1 ? '' : 's'})`
+        : `  ${r.name.padEnd(32)} ${r.status}${r.error ? ` (${r.error})` : ''}`;
+      log(line);
+    }
+    if (failures.length > 0) {
+      err(`[library refresh-clones] ${failures.length} tier${failures.length === 1 ? '' : 's'} failed`);
+    }
+  }
+  return failures.length === 0 ? 0 : 2;
+}
+
+async function enumerateTiers(root, only) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch { return []; }
+  const filter = only && only.length ? new Set(only) : null;
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    if (filter && !filter.has(entry.name)) continue;
+    const full = join(root, entry.name);
+    const s = await stat(join(full, '.git')).catch(() => null);
+    if (!s) continue;
+    out.push({ name: entry.name, path: full });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+async function refreshOne({ tier, git, timeoutMs }) {
+  const cwd = tier.path;
+
+  // Dirty check — refuse rather than clobber. Pull-clones are read-only
+  // projections; any local edit is a corruption signal that should be
+  // investigated, not merged over.
+  const dirty = await git(['status', '--porcelain'], cwd, { timeoutMs });
+  if (dirty.code !== 0) {
+    return { name: tier.name, status: 'error', error: `git status: ${(dirty.stderr || 'nonzero exit').slice(0, 160)}` };
+  }
+  if (dirty.stdout.trim() !== '') {
+    return { name: tier.name, status: 'dirty', error: 'uncommitted local changes; refusing to refresh' };
+  }
+
+  const fetched = await git(['fetch', '--quiet', 'origin'], cwd, { timeoutMs });
+  if (fetched.code !== 0) {
+    return { name: tier.name, status: 'error', error: `git fetch: ${(fetched.stderr || 'nonzero exit').slice(0, 160)}` };
+  }
+
+  const count = await git(['rev-list', 'HEAD..origin/main', '--count'], cwd, { timeoutMs });
+  const newCommits = count.code === 0 ? parseInt(count.stdout.trim(), 10) || 0 : 0;
+
+  if (newCommits === 0) {
+    return { name: tier.name, status: 'ok', newCommits: 0 };
+  }
+
+  const pulled = await git(['merge', '--ff-only', '--quiet', 'origin/main'], cwd, { timeoutMs });
+  if (pulled.code !== 0) {
+    return { name: tier.name, status: 'error', error: `git merge --ff-only: ${(pulled.stderr || 'nonzero exit').slice(0, 160)}` };
+  }
+  return { name: tier.name, status: 'ok', newCommits };
+}
+
+function runGit(argsArr, cwd, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIER_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    const proc = spawn('git', argsArr, { cwd });
+    let stdout = '';
+    let stderr = '';
+    const killer = setTimeout(() => {
+      stderr += `\n[timeout after ${timeoutMs}ms]`;
+      try { proc.kill('SIGTERM'); } catch { /* ignore */ }
+    }, timeoutMs);
+    proc.stdout.on('data', (b) => { stdout += b.toString('utf8'); });
+    proc.stderr.on('data', (b) => { stderr += b.toString('utf8'); });
+    proc.on('error', (e) => { clearTimeout(killer); resolve({ code: -1, stdout, stderr: e.message }); });
+    proc.on('close', (code) => { clearTimeout(killer); resolve({ code: code ?? -1, stdout, stderr }); });
+  });
+}
+
+function defaultLog(...m) { process.stdout.write(m.join(' ') + '\n'); }
+function defaultErr(...m) { process.stderr.write(m.join(' ') + '\n'); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Digital Operator PA \u2014 single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",