allye-pi 2.5.1 → 2.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allye Assistant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -83,10 +83,15 @@ Then add the `allye` MCP server as described in [install-pi.md](docs/install-pi.
 export ALLYE_PAT=pat_...                    # Allye → Settings → API
 ./install.sh list --scope team              # approved skills you can see
 ./install.sh install claude team-standards  # claude | codex | opencode | pi | omp
+./install.sh install claude team-standards --reinstall   # replace an edited copy (kept as a backup)
 ./install.sh status                         # offline integrity check
 ```
 
-Each install downloads the skill's approved release, verifies every file and the canonical hash, opens a distribution for this machine, verifies the API-signed execution token, publishes the files into the harness's user skills directory with a provenance sidecar, and records the result on the API. Local edits and directories it did not install are never overwritten. The API decides which runtimes may receive skills and who may distribute them; the installer reports its decision rather than working around it. Use `--team <id>` (or `ALLYE_TEAM_ID`) when you belong to several teams. Requires `bash`, `curl`, `jq` and Node.js 18+.
+Each install downloads the skill's approved release, verifies every file and the canonical hash, opens a distribution for this machine, verifies the API-signed execution token, publishes the files into the harness's user skills directory with a provenance sidecar, and records the result on the API. The API decides which runtimes may receive skills; the installer reports its decision rather than working around it. Requires `bash`, `curl`, `jq` and Node.js 18+. The installer speaks compatibility contract `1.1.0`.
+
+Until the allye-api PROD release that supports contract `1.1.0`, the installer works only against HML (`ALLYE_API_URL` pointing at the HML API). Against PROD it fails with `409 RUNTIME_INCOMPATIBLE` or an execution-context error about a missing signing key, and changes nothing.
+
+Who can install, where skills go, how edited, deleted and moved copies are handled, and the API errors are in [docs/org-skills.md](docs/org-skills.md).
 
 ## Repository layout
 
@@ -94,7 +99,7 @@ Each install downloads the skill's approved release, verifies every file and the
 bootstrap/allye.md          shared bootstrap text (single source)
 skills/bridge/              the Bridge skill and its references
 skills/bridge-*/            the crew skills (Armorer, Recon, Strategist, Architect, Dispatcher,
-                            Pilot, Copilot, Medic, Optimizer, Shield, Watcher)
+                            Pilot, Navigator, Copilot, Medic, Optimizer, Shield, Watcher)
 agents/bridge-*.md          native crew subagents (Claude Code; OpenCode registers them from here):
                             load the matching crew skill under a per-role tool allowlist
 hooks/                      Claude Code SessionStart hook
@@ -105,14 +110,14 @@ packages/allye-opencode/    OpenCode plugin (npm: allye-opencode)
 packages/allye-pi/          Pi/OMP extension (npm: allye-pi, root package.json)
 install.sh, install/        organization skills installer and its tests
 scripts/sync-bootstrap.sh   copies the bootstrap to manifests/codex/AGENTS.md
-docs/                       per-harness install and update guides
+docs/                       per-harness install and update guides, organization skills details
 ```
 
 ## Development
 
 ```bash
 npm install
-npm test            # bootstrap, hook, crew agents, installer and Pi extension tests (offline)
+npm test            # bootstrap, hook, crew agents, skills, installer and docs gate, Pi and OpenCode tests (offline)
 npm run typecheck   # Pi extension
 cd packages/allye-opencode && bun install && bun run typecheck && bun run build
 ```
@@ -125,4 +130,4 @@ Releases are automated by semantic-release on every push to `main` (Conventional
 
 ## License
 
-MIT
+MIT, see [LICENSE](LICENSE).

package/docs/install-omp.md

@@ -22,10 +22,18 @@ OMP has a native MCP client (no `pi-mcp-adapter`). Add the server once, at user
 
 OMP also loads servers from a project `.mcp.json`. Do not add tokens or OAuth client metadata: OMP discovers the OAuth endpoints and opens the browser on first use.
 
-Because OMP's MCP client is not the in-process `pi-mcp-adapter` bridge, the extension does not preload Allye context in OMP. It injects only the git remote and any unverified `.allye/project.json` claim; the bootstrap tells the agent to call `projects.project_resolve` itself. The team follows the project, so no team selection is needed.
+Because OMP's MCP client is not the in-process `pi-mcp-adapter` bridge (as in OMP today), the extension does not resolve the project. It injects only the git remote and any unverified `.allye/project.json` claim; the bootstrap tells the agent to call `projects.project_resolve` itself. The team follows the project, so no team selection is needed.
 
 ## Confirm
 
 Tell the user:
 
 > Allye is installed for OMP: the `allye-pi` extension (bootstrap and Bridge) and the `allye` MCP server. Start a new OMP session and run `/bridge survey` (or another mode).
+
+## Organization skills
+
+`./install.sh install omp <skill>` (see the [README](../README.md#your-organizations-skills)) installs into `~/.omp/agent/skills`. OMP presents itself to the API as runtime `pi`, and the skill is installed as a plain directory, with no package receipt.
+
+- Edited copies: `./install.sh install omp <skill> --reinstall` replaces your edited copy and keeps it at `~/.allye/backups/omp/<skill>.allye.backup.<UTC ts>`. A copy of the same release on the same target is already installed (a no-op); older-release copies are updated, and copies recorded for another target (after a hostname or skills-path change) are reinstalled when unchanged, while an edited one needs `--reinstall`. Foreign or unmanaged folders are never touched.
+- Leftovers: if the installer reports a `.allye-backup.<skill>.*` entry in the skills directory, an earlier run kept your edited folder there. Move it into `~/.allye/backups/omp/` or delete it, then rerun.
+- Any member with view access to a skill can install it. If the installer is too old for the API, upgrade the installer; there is nothing to ask an admin to reset. Until the allye-api PROD release the installer works only against HML. See the [README](../README.md#your-organizations-skills).

package/docs/install-pi.md

@@ -4,7 +4,7 @@ Allye for Pi is the native package `allye-pi`. It:
 
 - exposes the Bridge skill (`/bridge <mode>`) from the package's `skills/` directory;
 - adds the Allye bootstrap (`bootstrap/allye.md`) to the system prompt;
-- preloads Allye context (`initialize`, `intelligence`) when an in-process MCP bridge is available, and identifies the repository's project: it resolves the git remote with `projects.project_resolve` and verifies any `.allye/project.json` claim against it, injecting "this repo = project X / app Y (team Z)", the ambiguous candidates, or the disagreement to ask the user about.
+- identifies the repository's project (it loads no startup or per-prompt memory context): when an in-process MCP bridge is available it resolves the git remote with `projects.project_resolve` and verifies any `.allye/project.json` claim against it, injecting "this repo = project X / app Y (team Z)", the ambiguous candidates, or the disagreement to ask the user about.
 
 It never edits Pi's MCP configuration or reads credentials.
 
@@ -32,11 +32,11 @@ Do not pass headers, bearer tokens or OAuth client ids: Pi discovers the OAuth e
 
 On older Pi versions without `pi mcp`, install `pi-mcp-adapter` (`pi install npm:pi-mcp-adapter`), define one server named `allye` (`{"type": "http", "url": "https://mcp.allye.app/mcp"}` under `mcpServers`) in the effective source shown by `/mcp` — for example `~/.pi/agent/mcp.json` or `~/.config/mcp/mcp.json` — then run `/mcp-auth allye` and `/mcp reconnect allye`.
 
-The extension preloads Allye context only when `pi-mcp-adapter` exposes its in-process bridge. Otherwise it injects only the git remote and any unverified link claim, and the bootstrap tells the agent to call `projects.project_resolve` itself.
+The extension resolves the repository's project only when `pi-mcp-adapter` exposes its in-process bridge. Otherwise it injects only the git remote and any unverified link claim, and the bootstrap tells the agent to call `projects.project_resolve` itself.
 
 ## Teams
 
-The team follows the project: the extension never blocks work on team selection. A default team is needed only to create projects; `/allye-team <name|prefix|id>` sets it through the `team` tool (`team_set_default`). Set `ALLYE_PI_NATIVE_BOOTSTRAP=0` to skip the context preload (the bootstrap text and the Bridge skill stay available), or `ALLYE_PI_MCP=0` to disable MCP calls from the extension.
+The team follows the project: the extension never blocks work on team selection. A default team is needed only to create projects; `/allye-team <name|prefix|id>` sets it through the `team` tool (`team_set_default`). Set `ALLYE_PI_NATIVE_BOOTSTRAP=0` to skip the repository block (the bootstrap text and the Bridge skill stay available), or `ALLYE_PI_MCP=0` to disable MCP calls from the extension.
 
 ## Local development
 
@@ -48,3 +48,11 @@ npm run typecheck
 npm run test:pi
 pi -e ./packages/allye-pi/src/index.ts -p "Which Allye tools and Bridge modes are available?"
 ```
+
+## Organization skills
+
+`./install.sh install pi <skill>` (see the [README](../README.md#your-organizations-skills)) installs into `$PI_CODING_AGENT_DIR/skills` when `PI_CODING_AGENT_DIR` is set, otherwise `~/.pi/agent/skills`. The value must be an absolute path; only the empty string means unset, a trailing `/` is stripped, and a relative value stops the Pi install before any request. Changing it changes the install target; copies left in the old directory are not migrated. The API sees runtime `pi` and the skill is installed as a plain directory, with no package receipt.
+
+- Edited copies: `./install.sh install pi <skill> --reinstall` replaces your edited copy and keeps it at `~/.allye/backups/pi/<skill>.allye.backup.<UTC ts>`. A copy of the same release on the same target is already installed (a no-op); older-release copies are updated, and copies recorded for another target (after a hostname or skills-path change) are reinstalled when unchanged, while an edited one needs `--reinstall`. Foreign or unmanaged folders are never touched.
+- Leftovers: if the installer reports a `.allye-backup.<skill>.*` entry in the skills directory, an earlier run kept your edited folder there. Move it into `~/.allye/backups/pi/` or delete it, then rerun.
+- Any member with view access to a skill can install it. If the installer is too old for the API, upgrade the installer; there is nothing to ask an admin to reset. Until the allye-api PROD release the installer works only against HML. See the [README](../README.md#your-organizations-skills).

package/install/docs-check.mjs

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+// docs-check: deterministic checks for a repository's git docs (no dependencies).
+//
+//   node install/docs-check.mjs [--root <dir>] [file...]
+//
+// Files are relative to --root (default: the current directory). Without files it checks
+// README.md, AGENTS.md, CLAUDE.md and docs/**/*.md under the root (regular files only).
+// Rules, one line per finding `docs-check: <file>:<line>: <rule>: <message>`:
+//   link   - relative link targets exist inside the root; symlinks are resolved before
+//            existence is reported, so an escaping or dangling one is "outside root"
+//   anchor - `#anchor` and `file.md#anchor` match a GitHub heading slug of the target
+//            (exact, then case-insensitive) or an <a name|id> anchor
+//   fence  - backtick and tilde code fences (in list items or quotes too) are closed; a
+//            4-space indented code block outside a list is code, not a fence
+//   lines  - README.md <= 150, AGENTS.md <= 100, docs/ARCHITECTURE.md <= 300 lines; no
+//            line longer than 10000 characters (such a line is not parsed)
+// URLs with a scheme (http(s), mailto, kb-page:, ...) and protocol-relative URLs are
+// skipped, Allye URLs included. Fenced content and inline code are ignored for links and
+// headings. Exit 0 clean, 1 findings, 2 usage or file system error.
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+const USAGE = 'usage: node install/docs-check.mjs [--root <dir>] [file...]';
+const LIMITS = { 'README.md': 150, 'AGENTS.md': 100, 'docs/ARCHITECTURE.md': 300 };
+const DEFAULT_FILES = ['README.md', 'AGENTS.md', 'CLAUDE.md'];
+const MAX_LINE = 10000;
+
+class UsageError extends Error {}
+
+const toPosix = (p) => p.split(sep).join('/');
+const outside = (rel) => rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+
+function decode(s) {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+
+function parseArgs(argv) {
+  let root = '.';
+  const files = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--root') {
+      if (i + 1 >= argv.length) throw new UsageError('--root needs a directory');
+      root = argv[++i];
+    } else if (a.startsWith('-')) throw new UsageError(`unknown option ${a}`);
+    else files.push(a);
+  }
+  return { root, files };
+}
+
+function walkMarkdown(absDir, out) {
+  for (const name of readdirSync(absDir).sort()) {
+    const abs = join(absDir, name);
+    const st = lstatSync(abs);
+    if (st.isDirectory()) walkMarkdown(abs, out);
+    else if (st.isFile() && name.endsWith('.md')) out.push(abs);
+  }
+}
+
+// Removes inline code spans (a backtick run closed by the next run of the same length).
+function stripCode(line) {
+  const runs = [];
+  for (const m of line.matchAll(/`+/g)) runs.push({ start: m.index, len: m[0].length });
+  const next = new Array(runs.length).fill(-1);
+  const last = new Map();
+  for (let i = runs.length - 1; i >= 0; i--) {
+    next[i] = last.has(runs[i].len) ? last.get(runs[i].len) : -1;
+    last.set(runs[i].len, i);
+  }
+  let out = '';
+  let pos = 0;
+  for (let i = 0; i < runs.length; i++) {
+    if (runs[i].start < pos || next[i] === -1) continue;
+    const close = runs[next[i]];
+    out += line.slice(pos, runs[i].start);
+    pos = close.start + close.len;
+    i = next[i];
+  }
+  return out + line.slice(pos);
+}
+
+// nextOf(code, test)[i]: the first index >= i whose character passes test (n when none).
+function nextOf(code, test) {
+  const n = code.length;
+  const out = new Int32Array(n + 2).fill(n);
+  for (let i = n - 1; i >= 0; i--) out[i] = test(code[i]) ? i : out[i + 1];
+  return out;
+}
+
+// Inline link destinations `](dest)`, `](dest(with)(parens))`, `](<dest with spaces>)`,
+// `](dest "title")`. Linear: every lookup uses arrays precomputed in one pass, and a bare
+// destination ends at the first whitespace or at the `)` that unbalances its parentheses
+// (the next smaller prefix sum of +1 per `(` and -1 per `)`).
+function inlineLinks(code) {
+  const targets = [];
+  if (!code.includes('](')) return targets;
+  const n = code.length;
+  const isWs = (c) => c === ' ' || c === '\t';
+  const nextWs = nextOf(code, isWs);
+  const nextNonWs = nextOf(code, (c) => !isWs(c));
+  const nextChar = {};
+  for (const c of ['>', '"', "'", ')']) nextChar[c] = nextOf(code, (x) => x === c);
+  const sum = new Int32Array(n + 1);
+  for (let i = 0; i < n; i++) sum[i + 1] = sum[i] + (code[i] === '(' ? 1 : code[i] === ')' ? -1 : 0);
+  const nextLower = new Int32Array(n + 1).fill(n + 1);
+  const stack = [];
+  for (let k = n; k >= 0; k--) {
+    while (stack.length > 0 && sum[stack[stack.length - 1]] >= sum[k]) stack.pop();
+    if (stack.length > 0) nextLower[k] = stack[stack.length - 1];
+    stack.push(k);
+  }
+  let from = 0;
+  for (;;) {
+    const at = code.indexOf('](', from);
+    if (at === -1) break;
+    from = at + 2;
+    let p = nextNonWs[at + 2];
+    let target;
+    if (code[p] === '<') {
+      const end = nextChar['>'][p + 1];
+      if (end >= n) continue;
+      target = code.slice(p + 1, end);
+      p = end + 1;
+    } else {
+      const stop = Math.min(nextWs[p], nextLower[p] - 1);
+      if (stop >= n) continue;
+      target = code.slice(p, stop);
+      p = stop;
+    }
+    p = nextNonWs[p];
+    const q = code[p];
+    if (q === '"' || q === "'" || q === '(') {
+      const end = nextChar[q === '(' ? ')' : q][p + 1];
+      if (end >= n) continue;
+      p = nextNonWs[end + 1];
+    }
+    if (code[p] === ')' && target !== '') {
+      targets.push(target);
+      from = p + 1;
+    }
+  }
+  return targets;
+}
+
+// ATX heading text, or null. Linear: the closing `#` sequence is removed by hand.
+function atxHeading(line) {
+  const t = line.replace(/[ \t]+$/, '');
+  const m = /^ {0,3}(#{1,6})(?=[ \t]|$)/.exec(t);
+  if (!m) return null;
+  let text = t.slice(m[0].length).trim();
+  let j = text.length;
+  while (j > 0 && text[j - 1] === '#') j--;
+  if (j === 0) text = '';
+  else if (j < text.length && (text[j - 1] === ' ' || text[j - 1] === '\t')) text = text.slice(0, j).trim();
+  return text;
+}
+
+// Leading indentation in columns (a tab advances to the next multiple of 4).
+function columns(line) {
+  let col = 0;
+  for (const c of line) {
+    if (c === ' ') col++;
+    else if (c === '\t') col += 4 - (col % 4);
+    else break;
+  }
+  return col;
+}
+
+// Removes `_` emphasis delimiters that pair up (CommonMark flanking rules, closer matched
+// with the innermost opener of the same length); intraword and lone `_` are kept.
+function stripUnderscoreEmphasis(t) {
+  const word = (c) => c !== '' && /[\p{L}\p{N}]/u.test(c);
+  const space = (c) => c === '' || /\s/.test(c);
+  const runs = [];
+  const stack = [];
+  for (const m of t.matchAll(/_+/g)) {
+    const start = m.index;
+    const end = start + m[0].length;
+    const before = start > 0 ? t[start - 1] : '';
+    const after = end < t.length ? t[end] : '';
+    const run = { start, end, len: end - start, matched: false };
+    runs.push(run);
+    const top = stack[stack.length - 1];
+    if (!space(before) && !word(after) && top && top.len === run.len) {
+      top.matched = true;
+      run.matched = true;
+      stack.pop();
+    } else if (!space(after) && !word(before)) stack.push(run);
+  }
+  let out = '';
+  let pos = 0;
+  for (const r of runs) {
+    if (!r.matched) continue;
+    out += t.slice(pos, r.start);
+    pos = r.end;
+  }
+  return out + t.slice(pos);
+}
+
+// Line-by-line scan: fences, headings, and links outside fences.
+function scan(text) {
+  const lines = text.split('\n');
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  const headings = [];
+  const anchors = [];
+  const links = [];
+  const longLines = [];
+  let fence = null; // { char, len, line, marker }
+  let prev = null; // previous plain paragraph line (for setext headings)
+  let prevBlank = true;
+  let inList = false;
+  let inIndented = false; // inside a 4-space indented code block
+  for (let i = 0; i < lines.length; i++) {
+    const n = i + 1;
+    if (lines[i].length > MAX_LINE) {
+      longLines.push(n);
+      prev = null;
+      prevBlank = false;
+      continue;
+    }
+    const line = lines[i].replace(/\r$/, '').replace(/^(?: {0,3}> ?)+/, '');
+    const blank = line.trim() === '';
+    const wasBlank = prevBlank;
+    prevBlank = blank;
+    if (fence) {
+      const close = /^\s*(`{3,}|~{3,})\s*$/.exec(line);
+      if (close && close[1][0] === fence.char && close[1].length >= fence.len) fence = null;
+      continue;
+    }
+    const indent = columns(line);
+    if (inIndented && (blank || indent >= 4)) continue;
+    inIndented = false;
+    if (!blank && !inList && indent >= 4) {
+      // Outside a list, 4+ columns is an indented code block after a blank line, else a
+      // paragraph continuation; neither opens a fence.
+      if (wasBlank) {
+        inIndented = true;
+        prev = null;
+        continue;
+      }
+    } else if (!blank) {
+      if (/^[ \t]*(?:[-*+]|\d+[.)])(?:[ \t]|$)/.test(line)) inList = true;
+      else if (indent < 2) inList = false;
+    }
+    const open = inList || indent < 4 ? /^\s*(`{3,}|~{3,})(.*)$/.exec(line) : null;
+    if (open && !(open[1][0] === '`' && open[2].includes('`'))) {
+      fence = { char: open[1][0], len: open[1].length, line: n, marker: open[1] };
+      prev = null;
+      continue;
+    }
+    const heading = atxHeading(line);
+    if (heading !== null) {
+      headings.push(heading);
+      prev = null;
+    } else if (prev !== null && /^ {0,3}(?:=+|-+)[ \t]*$/.test(line)) {
+      headings.push(prev.trim());
+      prev = null;
+      continue;
+    } else if (line.trim() === '' || /^ {0,3}(?:[-*+>|]|\d+[.)])/.test(line)) {
+      prev = null;
+    } else {
+      prev = line;
+    }
+    // `<a ...>` tags, scanned linearly: each opener looks for the next `>` once, and none
+    // left means no later opener can close either.
+    const opener = /<a\s/gi;
+    for (let m; (m = opener.exec(line)); ) {
+      const end = line.indexOf('>', m.index);
+      if (end === -1) break;
+      const attr = /\b(?:name|id)\s*=\s*(?:"([^"]+)"|'([^']+)')/i.exec(line.slice(m.index, end + 1));
+      if (attr) anchors.push(attr[1] ?? attr[2]);
+      opener.lastIndex = end + 1;
+    }
+    const code = stripCode(line);
+    for (const target of inlineLinks(code)) links.push({ target, line: n });
+    const def = /^ {0,3}\[[^\]]+\]:[ \t]*(?:<([^>]*)>|(\S+))/.exec(code);
+    if (def) links.push({ target: def[1] ?? def[2], line: n });
+  }
+  return { lineCount: lines.length, headings, anchors, links, longLines, unclosed: fence };
+}
+
+// GitHub heading anchors (github-slugger): rendered text, lowercased, punctuation removed,
+// spaces to hyphens; a taken slug gets -1, -2, ... until it is free. Computed once per file.
+function slugs(doc) {
+  if (doc.slugs) return doc.slugs;
+  const occurrences = new Map();
+  for (const h of doc.headings) {
+    const text = stripUnderscoreEmphasis(
+      h
+        .replace(/!?\[([^[\]]*)\]\([^()]*\)/g, '$1')
+        .replace(/<[^<>]*>/g, '')
+        .replace(/`/g, ''),
+    );
+    const base = text
+      .toLowerCase()
+      .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, '')
+      .replace(/ /g, '-');
+    let slug = base;
+    while (occurrences.has(slug)) {
+      const count = occurrences.get(base) + 1;
+      occurrences.set(base, count);
+      slug = `${base}-${count}`;
+    }
+    occurrences.set(slug, 0);
+  }
+  const exact = new Set([...occurrences.keys(), ...doc.anchors]);
+  doc.slugs = { exact, lower: new Set([...exact].map((x) => x.toLowerCase())) };
+  return doc.slugs;
+}
+
+// Resolves every symlink of an absolute path, also when the path (or a link target) does
+// not exist: { real, exists }. A symlink loop resolves to the filesystem root.
+function resolveReal(p, depth = 0) {
+  if (depth > 40) return { real: resolve('/'), exists: false };
+  try {
+    return { real: realpathSync(p), exists: true };
+  } catch {
+    // fall through: p or one of its components does not resolve
+  }
+  const parent = dirname(p);
+  if (parent === p) return { real: p, exists: false };
+  let st = null;
+  try {
+    st = lstatSync(p);
+  } catch {
+    st = null;
+  }
+  if (st && st.isSymbolicLink()) {
+    return { real: resolveReal(resolve(dirname(p), readlinkSync(p)), depth + 1).real, exists: false };
+  }
+  return { real: join(resolveReal(parent, depth + 1).real, basename(p)), exists: false };
+}
+
+function main() {
+  const { root, files } = parseArgs(process.argv.slice(2));
+  const absRoot = resolve(root);
+  if (!existsSync(absRoot) || !statSync(absRoot).isDirectory()) throw new UsageError(`root is not a directory: ${root}`);
+  const realRoot = realpathSync(absRoot);
+  const escapes = (abs) => outside(relative(realRoot, realpathSync(abs)));
+
+  const targets = [];
+  if (files.length > 0) {
+    for (const f of files) {
+      const abs = resolve(absRoot, f);
+      if (outside(relative(absRoot, abs))) throw new UsageError(`file outside root: ${f}`);
+      if (!existsSync(abs) || !statSync(abs).isFile()) throw new UsageError(`no such file: ${f}`);
+      if (escapes(abs)) throw new UsageError(`file outside root: ${f}`);
+      targets.push(abs);
+    }
+  } else {
+    for (const f of DEFAULT_FILES) {
+      const abs = join(absRoot, f);
+      if (existsSync(abs) && lstatSync(abs).isFile()) targets.push(abs);
+    }
+    const docs = join(absRoot, 'docs');
+    if (existsSync(docs) && lstatSync(docs).isDirectory()) walkMarkdown(docs, targets);
+  }
+
+  // Keyed by real path: every read goes through the resolved path, never a symlink.
+  const cache = new Map();
+  const load = (real) => {
+    if (!cache.has(real)) cache.set(real, scan(readFileSync(real, 'utf8')));
+    return cache.get(real);
+  };
+  const findings = [];
+  for (const abs of targets) {
+    const rel = toPosix(relative(absRoot, abs));
+    const selfReal = realpathSync(abs);
+    const doc = load(selfReal);
+    const own = [];
+    const report = (line, rule, message) => own.push({ line, text: `docs-check: ${rel}:${line}: ${rule}: ${message}` });
+    for (const { target, line } of doc.links) {
+      if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//')) continue;
+      const hash = target.indexOf('#');
+      const beforeHash = hash === -1 ? target : target.slice(0, hash);
+      const anchor = hash === -1 ? '' : decode(target.slice(hash + 1));
+      const query = beforeHash.indexOf('?');
+      const pathPart = decode(query === -1 ? beforeHash : beforeHash.slice(0, query));
+      let dest = abs;
+      let real = selfReal;
+      if (pathPart !== '') {
+        dest = pathPart.startsWith('/') ? join(absRoot, pathPart) : resolve(dirname(abs), pathPart);
+        if (outside(relative(absRoot, dest))) {
+          report(line, 'link', `target outside root ${target}`);
+          continue;
+        }
+        // Containment before existence: a dangling or escaping symlink is "outside root".
+        const r = resolveReal(dest);
+        if (outside(relative(realRoot, r.real))) {
+          report(line, 'link', `target outside root ${target}`);
+          continue;
+        }
+        if (!r.exists) {
+          report(line, 'link', `missing target ${target}`);
+          continue;
+        }
+        real = r.real;
+      }
+      if (anchor === '' || !dest.endsWith('.md') || !statSync(real).isFile()) continue;
+      const known = slugs(load(real));
+      if (!known.exact.has(anchor) && !known.lower.has(anchor.toLowerCase())) {
+        report(line, 'anchor', `no heading for #${anchor} in ${toPosix(relative(absRoot, dest))}`);
+      }
+    }
+    if (doc.unclosed) report(doc.unclosed.line, 'fence', `unclosed ${doc.unclosed.marker} fence`);
+    for (const n of doc.longLines) report(n, 'lines', `line longer than ${MAX_LINE} characters`);
+    const limit = LIMITS[rel];
+    if (limit !== undefined && doc.lineCount > limit) report(limit + 1, 'lines', `${doc.lineCount} lines, limit ${limit}`);
+    own.sort((a, b) => a.line - b.line); // stable: a file's findings in line order
+    findings.push(...own.map((f) => f.text));
+  }
+
+  if (findings.length > 0) {
+    process.stdout.write(`${findings.join('\n')}\n`);
+    process.stderr.write(`docs-check: ${findings.length} finding(s)\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`docs-check: ok (${targets.length} files)\n`);
+}
+
+try {
+  main();
+} catch (err) {
+  if (err instanceof UsageError) {
+    process.stderr.write(`docs-check: ${err.message}\ndocs-check: ${USAGE}\n`);
+  } else {
+    process.stderr.write(`docs-check: error: ${err.message}\n`);
+  }
+  process.exit(2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allye-pi",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "Allye extension for Pi and OMP: the Allye bootstrap, the Bridge skill and the repository-to-project link",
   "type": "module",
   "keywords": [
@@ -15,6 +15,8 @@
     "packages/allye-pi/tsconfig.json",
     "skills",
     "bootstrap",
+    "templates/git-docs",
+    "install/docs-check.mjs",
     "docs/install-pi.md",
     "docs/install-omp.md",
     "LICENSE"
@@ -43,11 +45,13 @@
   "scripts": {
     "typecheck": "tsc --noEmit -p packages/allye-pi/tsconfig.json",
     "test:pi": "node --experimental-strip-types --test packages/allye-pi/src/index.test.ts",
-    "test:installer": "bash install/test-validation.sh && bash install/test-installer.sh",
+    "test:opencode": "node --experimental-strip-types --test packages/allye-opencode/src/skills-paths.test.ts",
+    "test:installer": "bash install/test-validation.sh && bash install/test-installer.sh && npm run test:docs-gate",
     "test:bootstrap": "bash test/test-bootstrap.sh && bash hooks/test-session-start.sh",
     "test:agents": "node test/test-agents.mjs",
-    "test:skills": "node test/test-skills-text.mjs && node test/test-ci-proof.mjs",
-    "test": "npm run test:bootstrap && npm run test:agents && npm run test:skills && npm run test:installer && npm run test:pi"
+    "test:docs-gate": "bash install/test-docs-gate.sh",
+    "test:skills": "node test/test-skills-text.mjs && node test/test-ci-proof.mjs && node test/test-ci-workflows.mjs",
+    "test": "npm run test:bootstrap && npm run test:agents && npm run test:skills && npm run test:installer && npm run test:pi && npm run test:opencode"
   },
   "repository": {
     "type": "git",