rigjs 3.0.32 → 4.0.2

package/lib/wiki/init.ts

@@ -0,0 +1,125 @@
+import fs from 'fs';
+import path from 'path';
+import print from '../print';
+import { guardPath, refusalMessage } from './pathGuard';
+
+const PURPOSE_TMPL = `# Purpose
+
+This wiki is <author>'s <scope> (single, do not mix).
+Key questions it aims to answer:
+- ...
+- ...
+What's in scope: ...
+What's out of scope: ...
+Audience: <author> + agents.
+`;
+
+const SCHEMA_TMPL = `# Schema
+
+## Layers
+- raw/, purpose.md, schema.md: read-only for LLM
+- wiki/, index.md, overview.md, log.md, reviews.md: LLM is sole author
+
+## Page types
+- sources/<slug>.md     : 1-source summary
+- entities/<slug>.md    : 1 thing with properties
+- concepts/<slug>.md    : 1 abstract idea
+- synthesis/<slug>.md   : cross-source integration
+- queries/<slug>.md     : archived Q&A worth keeping
+
+## Frontmatter (every wiki page MUST have)
+- type: source | entity | concept | synthesis | query
+- sources: [<source-slug>, ...]
+- source-sha: <sha>                # source pages only
+- source-path: raw/... | <relpath> # source pages only
+- ingested-at: <ISO>
+- last-updated: <ISO>
+
+## Naming
+- kebab-case; no spaces; no dates in wiki/ filenames
+- raw/ filenames keep YYYY-MM-DD prefix
+
+## Linking
+- use [[wikilink]] to other wiki pages by slug
+- every wiki page must link to >=1 other page or be flagged orphan
+
+## Contradictions
+- flag inline: > Contradiction: A vs B (see [[source-A]], [[source-B]])
+- never silently merge; lint surfaces them for human resolution
+
+## Hard rules
+- never edit raw/, purpose.md, schema.md
+- raw/ file sha drift = error, not a re-ingest trigger
+- living-doc paths (in include[]) sha drift = MODIFIED, propose re-ingest
+`;
+
+const SUBDIRS = ['sources', 'entities', 'concepts', 'synthesis', 'queries'];
+
+// What lives inside the wiki dir but must not enter git / Obsidian Sync:
+// - qmd's project-local vector cache (sqlite-vec, non-deterministic, rebuilds
+//   locally with `rig wiki index` / `rig wiki rebuild`)
+// - lint reports (auto-regenerated)
+// - daemon proposal diffs (transient, per-machine)
+// - editor scratch
+const GITIGNORE_TMPL = `# rig wiki — local-only artifacts (do not commit)
+# qmd vector cache (sqlite-vec, machine-specific, rebuildable)
+.qmd/index.sqlite*
+.qmd/*.sqlite-wal
+.qmd/*.sqlite-shm
+# auto-generated reports
+lint-report-*.md
+# daemon proposal queue (per-machine)
+proposals/
+# editor scratch
+.DS_Store
+*.swp
+`;
+
+export default function wikiInit(givenPath?: string): void {
+  if (!givenPath || !givenPath.trim()) {
+    print.error('rig wiki init requires a target subdirectory.');
+    print.info('usage: rig wiki init <subdir>     (e.g. `rig wiki init knowledge` / `rig wiki init harness/llm-wiki`)');
+    print.info('refusing to default to CWD — that would litter the project root with wiki templates.');
+    process.exit(1);
+  }
+  const root = path.resolve(givenPath);
+  const guard = guardPath(root, process.cwd());
+  if (!guard.ok) {
+    print.error('refusing to initialize a wiki at a hidden or gitignored path.');
+    // eslint-disable-next-line no-console
+    console.error(refusalMessage(root, guard));
+    process.exit(1);
+  }
+  fs.mkdirSync(root, { recursive: true });
+
+  writeIfMissing(path.join(root, 'purpose.md'), PURPOSE_TMPL);
+  writeIfMissing(path.join(root, 'schema.md'), SCHEMA_TMPL);
+  writeIfMissing(path.join(root, 'index.md'), '# Index\n');
+  writeIfMissing(path.join(root, 'overview.md'), '# Overview\n');
+  writeIfMissing(path.join(root, 'log.md'), '# Log\n');
+  writeIfMissing(path.join(root, 'reviews.md'), '# Reviews\n');
+  writeIfMissing(path.join(root, '.gitignore'), GITIGNORE_TMPL);
+
+  fs.mkdirSync(path.join(root, 'raw'), { recursive: true });
+  writeIfMissing(path.join(root, 'raw', '.gitkeep'), '');
+
+  for (const sub of SUBDIRS) {
+    const d = path.join(root, 'wiki', sub);
+    fs.mkdirSync(d, { recursive: true });
+    writeIfMissing(path.join(d, '.gitkeep'), '');
+  }
+
+  print.succeed(`wiki initialized at ${root}`);
+  print.info(`next: edit purpose.md + schema.md, then \`rig wiki register ${shortPath(root)}\``);
+  print.info('on a new device, after cloning, run `rig wiki rebuild` to refresh local caches.');
+}
+
+function writeIfMissing(file: string, content: string) {
+  if (fs.existsSync(file)) return;
+  fs.writeFileSync(file, content, 'utf8');
+}
+
+function shortPath(p: string) {
+  const home = process.env.HOME || '';
+  return home && p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}

package/lib/wiki/installSkill.ts

@@ -0,0 +1,92 @@
+import fs from 'fs';
+import path from 'path';
+import print from '../print';
+import { paths } from './paths';
+
+const BUNDLED_SKILLS = [
+  { name: 'rig-wiki', file: 'RIG_WIKI_SKILL.md' },
+  { name: 'rig-crew', file: 'RIG_CREW_SKILL.md' },
+];
+
+/** Find rig's package root by walking up from built/ or lib/. */
+function findRigRoot(): string | undefined {
+  // Walk up from `built/index.js` (prod) or `lib/wiki/installSkill.ts` (dev)
+  // looking for the rigjs package root.
+  let dir = __dirname;
+  for (let i = 0; i < 10; i++) {
+    const pkg = path.join(dir, 'package.json');
+    if (fs.existsSync(pkg)) {
+      try {
+        const p = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+        if (p.name === 'rigjs') return dir;
+      } catch { /* keep walking */ }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+interface InstallOpts { force?: boolean; }
+
+export default function wikiInstallSkill(opts: InstallOpts): void {
+  const root = findRigRoot();
+  if (!root) {
+    print.error('could not locate the rigjs install root. Reinstall rigjs?');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(paths.claudeSkillsDir)) {
+    print.error(`Claude Code skills dir not found: ${paths.claudeSkillsDir}`);
+    print.info('install Claude Code first, then re-run `rig wiki install-skill`.');
+    process.exit(1);
+  }
+
+  for (const skill of BUNDLED_SKILLS) {
+    const src = path.join(root, skill.file);
+    if (!fs.existsSync(src)) {
+      print.warn(`skipping ${skill.name}: ${skill.file} not found inside rigjs install`);
+      continue;
+    }
+    linkSkill(skill.name, src, opts);
+  }
+
+  print.info('restart Claude Code to pick up new or updated skills.');
+}
+
+function linkSkill(name: string, src: string, opts: InstallOpts): void {
+  const targetDir = path.join(paths.claudeSkillsDir, name);
+  const target = path.join(targetDir, 'SKILL.md');
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  if (fs.existsSync(target) || isBrokenSymlink(target)) {
+    const existing = safeReadlink(target);
+    if (existing === src) {
+      print.info(`already linked: ${target}`);
+      return;
+    }
+    if (!opts.force) {
+      const what = existing ? `symlink -> ${existing}` : 'a regular file';
+      print.error(`${target} exists as ${what}. Pass --force to replace.`);
+      process.exit(1);
+    }
+    fs.rmSync(target, { force: true });
+  }
+
+  fs.symlinkSync(src, target);
+  print.succeed(`linked ${target} -> ${src}`);
+}
+
+function safeReadlink(p: string): string | null {
+  try { return fs.readlinkSync(p); } catch { return null; }
+}
+
+function isBrokenSymlink(p: string): boolean {
+  try {
+    fs.statSync(p);
+    return false;
+  } catch {
+    try { return Boolean(fs.readlinkSync(p)); } catch { return false; }
+  }
+}

package/lib/wiki/lint.ts

@@ -0,0 +1,252 @@
+// `rig wiki lint` — health-check a wiki.
+//
+// Checks:
+//   - every wiki/**/*.md has YAML frontmatter with required keys
+//   - source pages reference a real raw/ file and the recorded source-sha
+//     still matches (drift → MODIFIED, not an error in lint, just info)
+//   - [[wikilink]] targets exist (broken refs → severe)
+//   - orphan pages (linked-by 0, excluding sources/) → warn
+//   - reviews.md backlog count → warn
+//
+// Output: human-readable summary on stdout, full report at
+// <wiki>/lint-report-YYYY-MM-DD.md.
+// Exit 11 if any severe finding. Other findings are non-fatal.
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import print from '../print';
+import { loadWikiConfig, resolveWiki, WikiEntry } from './config';
+import { recordLastRun } from './db';
+
+interface LintOpts { wiki?: string; all?: boolean; json?: boolean; }
+
+interface PageMeta {
+  rel: string;          // wiki-relative path, e.g. "wiki/sources/foo.md"
+  slug: string;         // filename without ext
+  sub: string;          // "sources" | "entities" | "concepts" | "synthesis" | "queries"
+  frontmatter: Record<string, unknown> | null;
+  links: string[];      // [[wikilink]] targets
+}
+
+interface Findings {
+  missingFrontmatter: string[];
+  missingRequiredKey: { rel: string; key: string }[];
+  brokenWikilinks: { rel: string; target: string }[];
+  missingRawSource: { rel: string; sourcePath: string }[];
+  shaDriftSource: { rel: string; oldSha: string; newSha: string }[];
+  orphanPages: string[];
+  reviewsBacklog: number;
+}
+
+const REQUIRED_KEYS = ['type', 'sources', 'ingested-at', 'last-updated'] as const;
+const SOURCE_EXTRA_KEYS = ['source-sha', 'source-path'] as const;
+const WIKI_SUBDIRS = ['sources', 'entities', 'concepts', 'synthesis', 'queries'] as const;
+
+export default async function wikiLint(opts: LintOpts): Promise<void> {
+  const cfg = loadWikiConfig();
+  const targets: WikiEntry[] = opts.all
+    ? cfg.wikis
+    : [resolveWiki(cfg, opts.wiki)].filter(Boolean) as WikiEntry[];
+  if (targets.length === 0) {
+    print.error('no wiki resolved. Pass --wiki <name>, --all, or run from inside a registered project.');
+    process.exit(1);
+  }
+
+  let severeFound = false;
+  const reports: { wiki: string; findings: Findings }[] = [];
+  for (const t of targets) {
+    const findings = lintOne(t);
+    reports.push({ wiki: t.name, findings });
+    const sev =
+      findings.missingFrontmatter.length +
+      findings.missingRequiredKey.length +
+      findings.brokenWikilinks.length +
+      findings.missingRawSource.length;
+    if (sev > 0) severeFound = true;
+    if (!opts.json) printSummary(t.name, findings);
+    writeReport(t, findings);
+    recordLastRun(t.name, 'lint', sev > 0 ? 11 : 0);
+  }
+
+  if (opts.json) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify({ ok: !severeFound, code: severeFound ? 11 : 0, data: reports }, null, 2));
+  }
+  if (severeFound) process.exit(11);
+}
+
+function lintOne(wiki: WikiEntry): Findings {
+  const f: Findings = {
+    missingFrontmatter: [],
+    missingRequiredKey: [],
+    brokenWikilinks: [],
+    missingRawSource: [],
+    shaDriftSource: [],
+    orphanPages: [],
+    reviewsBacklog: 0,
+  };
+
+  const pages: PageMeta[] = [];
+  for (const sub of WIKI_SUBDIRS) {
+    const dir = path.join(wiki.path, 'wiki', sub);
+    if (!fs.existsSync(dir)) continue;
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.md') || name === '.gitkeep') continue;
+      const abs = path.join(dir, name);
+      pages.push(parsePage(wiki.path, abs, sub));
+    }
+  }
+
+  const slugToRel = new Map<string, string>();
+  for (const p of pages) slugToRel.set(p.slug, p.rel);
+
+  const linkedSlugs = new Set<string>();
+  for (const p of pages) {
+    if (!p.frontmatter) { f.missingFrontmatter.push(p.rel); continue; }
+    for (const k of REQUIRED_KEYS) {
+      if (!(k in p.frontmatter)) f.missingRequiredKey.push({ rel: p.rel, key: k });
+    }
+    if (p.sub === 'sources') {
+      for (const k of SOURCE_EXTRA_KEYS) {
+        if (!(k in p.frontmatter)) f.missingRequiredKey.push({ rel: p.rel, key: k });
+      }
+      const sourcePath = String(p.frontmatter['source-path'] || '');
+      if (sourcePath) {
+        const abs = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(wiki.path, sourcePath);
+        if (!fs.existsSync(abs)) {
+          f.missingRawSource.push({ rel: p.rel, sourcePath });
+        } else {
+          const newSha = sha256(abs);
+          const oldSha = String(p.frontmatter['source-sha'] || '');
+          if (oldSha && oldSha !== newSha) f.shaDriftSource.push({ rel: p.rel, oldSha, newSha });
+        }
+      }
+    }
+    for (const target of p.links) {
+      if (!slugToRel.has(target)) {
+        f.brokenWikilinks.push({ rel: p.rel, target });
+      } else {
+        linkedSlugs.add(target);
+      }
+    }
+  }
+
+  // Orphans: non-source pages that nothing else links to. Sources may
+  // legitimately have no inbound links until ingested into a synthesis.
+  for (const p of pages) {
+    if (p.sub === 'sources') continue;
+    if (!linkedSlugs.has(p.slug)) f.orphanPages.push(p.rel);
+  }
+
+  // Reviews backlog: count non-empty bullet lines in reviews.md.
+  const reviewsPath = path.join(wiki.path, 'reviews.md');
+  if (fs.existsSync(reviewsPath)) {
+    const lines = fs.readFileSync(reviewsPath, 'utf8').split('\n');
+    f.reviewsBacklog = lines.filter(l => /^\s*[-*]\s+\S/.test(l)).length;
+  }
+
+  return f;
+}
+
+function parsePage(wikiRoot: string, abs: string, sub: string): PageMeta {
+  const rel = path.relative(wikiRoot, abs);
+  const slug = path.basename(abs, path.extname(abs));
+  const content = fs.readFileSync(abs, 'utf8');
+  const { frontmatter, body } = splitFrontmatter(content);
+  const links = extractWikilinks(body);
+  return { rel, slug, sub, frontmatter, links };
+}
+
+function splitFrontmatter(content: string): { frontmatter: Record<string, unknown> | null; body: string } {
+  if (!content.startsWith('---\n')) return { frontmatter: null, body: content };
+  const end = content.indexOf('\n---\n', 4);
+  if (end < 0) return { frontmatter: null, body: content };
+  const yaml = content.slice(4, end);
+  const body = content.slice(end + 5);
+  return { frontmatter: parseTinyYaml(yaml), body };
+}
+
+// Minimal YAML parser — handles the rig wiki frontmatter shape only
+// (key: scalar / key: [a, b, c]). Anything else returns null for that key.
+function parseTinyYaml(src: string): Record<string, unknown> | null {
+  const out: Record<string, unknown> = {};
+  for (const line of src.split('\n')) {
+    const trimmed = line.replace(/#.*$/, '').trimEnd();
+    if (!trimmed) continue;
+    const m = /^([A-Za-z][\w-]*)\s*:\s*(.*)$/.exec(trimmed);
+    if (!m) continue;
+    const [, key, valRaw] = m;
+    const val = valRaw.trim();
+    if (val.startsWith('[') && val.endsWith(']')) {
+      out[key] = val.slice(1, -1).split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+    } else {
+      out[key] = val.replace(/^['"]|['"]$/g, '');
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+function extractWikilinks(body: string): string[] {
+  const out: string[] = [];
+  const re = /\[\[([^\]|\n]+)(?:\|[^\]]*)?\]\]/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(body)) !== null) {
+    const slug = m[1].trim().split('#')[0].split('/').pop() || '';
+    if (slug) out.push(slug);
+  }
+  return out;
+}
+
+function sha256(file: string): string {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function printSummary(wikiName: string, f: Findings): void {
+  print.info(`lint: ${wikiName}`);
+  const lines: string[] = [];
+  if (f.missingFrontmatter.length) lines.push(`  MISSING FRONTMATTER (${f.missingFrontmatter.length})`);
+  if (f.missingRequiredKey.length) lines.push(`  MISSING REQUIRED KEY (${f.missingRequiredKey.length})`);
+  if (f.brokenWikilinks.length) lines.push(`  BROKEN WIKILINKS (${f.brokenWikilinks.length})`);
+  if (f.missingRawSource.length) lines.push(`  MISSING RAW SOURCE (${f.missingRawSource.length})`);
+  if (f.shaDriftSource.length) lines.push(`  SOURCE SHA DRIFT (${f.shaDriftSource.length})  [info — propose re-ingest]`);
+  if (f.orphanPages.length) lines.push(`  ORPHAN PAGES (${f.orphanPages.length})  [warn]`);
+  if (f.reviewsBacklog) lines.push(`  REVIEWS BACKLOG (${f.reviewsBacklog} item${f.reviewsBacklog === 1 ? '' : 's'})  [warn]`);
+  if (lines.length === 0) {
+    print.succeed('  clean');
+  } else {
+    for (const l of lines) {
+      // eslint-disable-next-line no-console
+      console.log(l);
+    }
+  }
+}
+
+function writeReport(wiki: WikiEntry, f: Findings): void {
+  const today = new Date().toISOString().slice(0, 10);
+  const out = path.join(wiki.path, `lint-report-${today}.md`);
+  const parts: string[] = [];
+  parts.push(`# lint report — ${wiki.name} — ${today}`);
+  parts.push('');
+  parts.push(`Generated by \`rig wiki lint\`. Severe sections trigger exit code 11.`);
+  parts.push('');
+
+  section(parts, 'Missing frontmatter (severe)', f.missingFrontmatter.map(r => `- ${r}`));
+  section(parts, 'Missing required key (severe)', f.missingRequiredKey.map(x => `- ${x.rel} — \`${x.key}\``));
+  section(parts, 'Broken wikilinks (severe)', f.brokenWikilinks.map(x => `- ${x.rel} → [[${x.target}]]`));
+  section(parts, 'Missing raw source (severe)', f.missingRawSource.map(x => `- ${x.rel} → ${x.sourcePath}`));
+  section(parts, 'Source sha drift (re-ingest recommended)', f.shaDriftSource.map(x => `- ${x.rel}\n  - old: \`${x.oldSha.slice(0, 12)}…\`\n  - new: \`${x.newSha.slice(0, 12)}…\``));
+  section(parts, 'Orphan pages', f.orphanPages.map(r => `- ${r}`));
+  parts.push(`## Reviews backlog\n\n${f.reviewsBacklog} item(s).`);
+  parts.push('');
+
+  fs.writeFileSync(out, parts.join('\n'), 'utf8');
+}
+
+function section(out: string[], title: string, items: string[]): void {
+  out.push(`## ${title}`);
+  out.push('');
+  if (items.length === 0) out.push('_(none)_');
+  else for (const item of items) out.push(item);
+  out.push('');
+}

package/lib/wiki/list.ts

@@ -0,0 +1,69 @@
+import fs from 'fs';
+import path from 'path';
+import print from '../print';
+import { loadWikiConfig, loadRigConfig } from './config';
+import { getLastRun } from './db';
+import { detectQmd } from './qmd';
+import { adapters } from './agent/registry';
+
+export default async function wikiList(): Promise<void> {
+  const cfg = loadWikiConfig();
+  const rig = loadRigConfig();
+  if (cfg.wikis.length === 0) {
+    print.info('no wikis registered. Use `rig wiki register [<path>]` to add one.');
+  } else {
+    const rows = cfg.wikis.map(w => ({
+      name: w.name,
+      path: shortPath(w.path),
+      pages: countPages(w.path),
+      lastScan: fmtTs(getLastRun(w.name, 'scan')?.ts),
+      lastIngest: fmtTs(getLastRun(w.name, 'ingest')?.ts),
+      lastLint: fmtTs(getLastRun(w.name, 'lint')?.ts),
+    }));
+    const header = ['NAME', 'PATH', 'PAGES', 'LAST SCAN', 'LAST INGEST', 'LAST LINT'];
+    printTable(header, rows.map(r => [r.name, r.path, String(r.pages), r.lastScan, r.lastIngest, r.lastLint]));
+  }
+
+  const qmd = detectQmd();
+  const defaultAgent = rig.wiki?.defaultAgent || 'claude';
+  const agentDetect = await adapters.find(a => a.name === defaultAgent)?.detect();
+  // eslint-disable-next-line no-console
+  console.log(`\nagent: ${defaultAgent}${agentDetect?.installed ? ` (${agentDetect.version || 'installed'})` : ' (NOT installed)'}` +
+              `   qmd: ${qmd.installed ? qmd.version || 'installed' : 'not installed (fallback mode)'}`);
+}
+
+function countPages(wikiDir: string): number {
+  const wiki = path.join(wikiDir, 'wiki');
+  if (!fs.existsSync(wiki)) return 0;
+  let n = 0;
+  for (const sub of ['sources', 'entities', 'concepts', 'synthesis', 'queries']) {
+    const d = path.join(wiki, sub);
+    if (!fs.existsSync(d)) continue;
+    for (const f of fs.readdirSync(d)) if (f.endsWith('.md') && f !== '.gitkeep') n++;
+  }
+  return n;
+}
+
+function shortPath(p: string): string {
+  const home = process.env.HOME || '';
+  return home && p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+
+function fmtTs(ts?: number): string {
+  if (!ts) return '—';
+  const d = new Date(ts);
+  return d.toISOString().replace('T', ' ').slice(0, 16);
+}
+
+function printTable(header: string[], rows: string[][]): void {
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map(r => (r[i] || '').length)));
+  const fmt = (cells: string[]) => cells.map((c, i) => (c || '').padEnd(widths[i])).join('  ');
+  // eslint-disable-next-line no-console
+  console.log(fmt(header));
+  // eslint-disable-next-line no-console
+  console.log(widths.map(w => '-'.repeat(w)).join('  '));
+  for (const r of rows) {
+    // eslint-disable-next-line no-console
+    console.log(fmt(r));
+  }
+}

package/lib/wiki/pathGuard.ts

@@ -0,0 +1,87 @@
+// Shared guards for rig wiki — refuse to operate on hidden paths or
+// .gitignored content. The user must explicitly copy such files into a
+// visible, tracked location before they can become wiki sources.
+
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+export interface PathGuardResult {
+  ok: boolean;
+  reason?: 'hidden' | 'gitignored';
+  segment?: string;       // for hidden: the offending segment
+  detail?: string;        // human-readable detail
+}
+
+/** True if any path segment (except `.` / `..`) starts with `.`. */
+export function isHiddenPath(p: string): boolean {
+  for (const seg of segmentsOf(p)) {
+    if (seg.startsWith('.')) return true;
+  }
+  return false;
+}
+
+/** First hidden segment, or null. */
+export function hiddenSegment(p: string): string | null {
+  for (const seg of segmentsOf(p)) {
+    if (seg.startsWith('.')) return seg;
+  }
+  return null;
+}
+
+function segmentsOf(p: string): string[] {
+  return p.split(path.sep).filter(s => s && s !== '.' && s !== '..');
+}
+
+/**
+ * Returns true if the path is ignored by git in `repoCwd`'s repo.
+ * Returns false if tracked/non-ignored. Returns null if not in a git repo
+ * (so callers can pass the check transparently outside git contexts).
+ */
+export function isGitignored(p: string, repoCwd: string): boolean | null {
+  const r = spawnSync('git', ['check-ignore', '-q', '--', p], {
+    cwd: repoCwd,
+    encoding: 'utf8',
+  });
+  if (r.status === 0) return true;   // ignored
+  if (r.status === 1) return false;  // not ignored
+  return null;                       // exit 128 (not a repo) or git missing
+}
+
+/**
+ * Validate a path as a wiki source / target. Returns ok if visible AND
+ * not gitignored. Use for `init` target and `ingest` source.
+ */
+export function guardPath(absPath: string, repoCwd: string): PathGuardResult {
+  const seg = hiddenSegment(absPath);
+  if (seg) {
+    return {
+      ok: false,
+      reason: 'hidden',
+      segment: seg,
+      detail: `path contains a hidden segment "${seg}"`,
+    };
+  }
+  const gi = isGitignored(absPath, repoCwd);
+  if (gi === true) {
+    return {
+      ok: false,
+      reason: 'gitignored',
+      detail: '.gitignore matches this path',
+    };
+  }
+  return { ok: true };
+}
+
+export function refusalMessage(target: string, r: PathGuardResult): string {
+  const lines = [
+    `refused: ${target}`,
+    `  reason: ${r.reason} — ${r.detail}`,
+    '',
+    '  rig wiki refuses to operate on hidden files/dirs or .gitignored content.',
+    '  If you really need this content, copy it to a visible, tracked location first:',
+    '',
+    '    cp -R <hidden-or-ignored> <wiki>/raw/manual-copy/    # then `rig wiki ingest`',
+    '',
+  ];
+  return lines.join('\n');
+}

package/lib/wiki/paths.ts

@@ -0,0 +1,29 @@
+import os from 'os';
+import path from 'path';
+
+export const RIG_HOME = process.env.RIG_HOME || path.join(os.homedir(), '.rig');
+
+export const paths = {
+  home: RIG_HOME,
+  config: path.join(RIG_HOME, 'config.json5'),
+  wikiConfig: path.join(RIG_HOME, 'wiki.config.json5'),
+  stateDb: path.join(RIG_HOME, 'state.db'),
+  locks: path.join(RIG_HOME, 'locks'),
+  logs: path.join(RIG_HOME, 'logs'),
+  daemonLog: path.join(RIG_HOME, 'logs', 'wiki-daemon.log'),
+  cache: path.join(RIG_HOME, 'cache'),
+  sandbox: path.join(RIG_HOME, 'cache', 'sandbox'),
+  launchAgent: path.join(os.homedir(), 'Library', 'LaunchAgents', 'ai.flashhand.rig.wiki.plist'),
+  claudeSkillsDir: path.join(os.homedir(), '.claude', 'skills'),
+  builtinSkillRelative: 'RIG_WIKI_SKILL.md',
+};
+
+export const daemonLabel = 'ai.flashhand.rig.wiki';
+
+export function wikiLogDir(wikiName: string) {
+  return path.join(paths.logs, 'wikis', wikiName);
+}
+
+export function wikiLockFile(wikiName: string) {
+  return path.join(paths.locks, `${wikiName}.lock`);
+}

package/lib/wiki/platform.ts

@@ -0,0 +1,8 @@
+import print from '../print';
+
+export function requireMacOS(): void {
+  if (process.platform !== 'darwin') {
+    print.error(`rig wiki currently supports macOS only (detected: ${process.platform}). Linux support is on the P5 roadmap; Windows is not planned.`);
+    process.exit(32);
+  }
+}