@garygentry/feature-forge 0.1.4 → 0.2.0

package/dist/placements.js

@@ -0,0 +1,116 @@
+/**
+ * Secondary install placements (A4b) — the second-root generalization the single-`destination`
+ * install model can't express. Two kinds (see {@link PlacementKind}):
+ *   - "mirror"        — codex copies the bundle's `agents/*.toml` FLAT into `.codex/agents/`, where
+ *                       Codex loads custom agents (it does NOT read them from `.agents/skills`).
+ *   - "managed-block" — copilot writes a sentinel-delimited pointer block into the (possibly
+ *                       user-owned) `.github/copilot-instructions.md`, preserving the rest of it.
+ *
+ * This module is PURE: it resolves declarative {@link PlacementSpec}s to absolute roots, selects the
+ * mirror source files, and provides the managed-block string transforms (render/upsert/remove/read).
+ * The planner (plan.ts) decides actions and the apply engine (apply.ts) executes them; neither knows
+ * the per-kind string mechanics — those live here. Zero runtime dependencies; only `node:` built-ins.
+ */
+import * as path from "node:path";
+import { MANAGED_BLOCK_END, MANAGED_BLOCK_START, } from "./types.js";
+import { resolveRoots } from "./agent-targets.js";
+/**
+ * Resolve every secondary placement declared on `target` to absolute roots under `scope` (A4b).
+ * Returns `[]` for agents with no placements (claude/cursor/gemini). Pure; the single derivation
+ * point so a new rule stays one `AGENT_TARGETS` edit (REQ-SCALE-01).
+ */
+export function resolvePlacements(target, scope, opts) {
+    const roots = resolveRoots(opts);
+    const scopeRoot = scope === "global" ? roots.home : roots.cwd;
+    return (target.placements ?? []).map((spec) => {
+        const root = path.resolve(scopeRoot, spec.baseDir);
+        return { kind: spec.kind, root, destination: path.resolve(root, spec.subpath), spec };
+    });
+}
+/**
+ * Select the bundle files a "mirror" placement copies (A4b): every `source.files` entry whose
+ * POSIX relpath starts with `spec.sourcePrefix`, copied FLAT (basename only) into the destination.
+ * Sorted by destination basename for deterministic plans. Pure.
+ */
+export function selectMirrorFiles(source, spec) {
+    const prefix = spec.sourcePrefix ?? "";
+    return source.files
+        .filter((f) => f.relpath.startsWith(prefix))
+        .map((f) => ({ srcRelpath: f.relpath, destRelpath: path.posix.basename(f.relpath), srcHash: f.sha256 }))
+        .sort((a, b) => (a.destRelpath < b.destRelpath ? -1 : a.destRelpath > b.destRelpath ? 1 : 0));
+}
+// ---------------------------------------------------------------------------
+// Managed-block string transforms (pure)
+// ---------------------------------------------------------------------------
+/**
+ * Render the managed-block BODY (without sentinels) for copilot (A4b). Points Copilot — which has no
+ * skills loader — at the staged bundle under `.github/feature-forge/` and lists the available skills.
+ * Deterministic given the bundle's skill ids. Pure.
+ */
+export function renderCopilotBlock(skills) {
+    const lines = [
+        "# feature-forge",
+        "",
+        "The feature-forge skill suite is installed in this repository under",
+        "`.github/feature-forge/`. GitHub Copilot has no skills loader, so consult those files",
+        "directly when a feature-forge workflow is requested.",
+        "",
+        "Each skill lives at `.github/feature-forge/skills/<name>/SKILL.md`. Available skills:",
+        "",
+        ...[...skills].sort().map((s) => `- ${s}`),
+        "",
+        "Shared references are under `.github/feature-forge/references/`; helper scripts under",
+        "`.github/feature-forge/scripts/`.",
+    ];
+    return lines.join("\n");
+}
+/** Wrap a rendered block body in the managed sentinels — the exact region written on disk. */
+export function wrapBlock(body) {
+    return `${MANAGED_BLOCK_START}\n${body}\n${MANAGED_BLOCK_END}`;
+}
+/**
+ * Extract the full managed region (sentinels INCLUDED) currently present in `content`, or `null` if
+ * no well-formed `start…end` region exists. The region is what `wrapBlock` produces, so its hash is
+ * directly comparable to a freshly rendered block. Pure.
+ */
+export function extractManagedRegion(content) {
+    const startIdx = content.indexOf(MANAGED_BLOCK_START);
+    if (startIdx === -1)
+        return null;
+    const endIdx = content.indexOf(MANAGED_BLOCK_END, startIdx + MANAGED_BLOCK_START.length);
+    if (endIdx === -1)
+        return null;
+    return content.slice(startIdx, endIdx + MANAGED_BLOCK_END.length);
+}
+/**
+ * Insert or replace the managed block in `existing`, preserving all user content outside the
+ * sentinels (A4b). If a region exists it is replaced in place; otherwise the block is appended after
+ * the existing content (separated by a blank line). `existing` is `""` for a not-yet-created file.
+ * The result always ends with a single trailing newline. Pure.
+ */
+export function upsertBlock(existing, body) {
+    const region = wrapBlock(body);
+    const current = extractManagedRegion(existing);
+    if (current !== null) {
+        return ensureTrailingNewline(existing.replace(current, region));
+    }
+    if (existing.trim() === "")
+        return ensureTrailingNewline(region);
+    return ensureTrailingNewline(`${existing.replace(/\n+$/, "")}\n\n${region}`);
+}
+/**
+ * Remove the managed block from `existing`, preserving the rest (A4b uninstall). Returns the
+ * remaining content (trailing whitespace trimmed to a single newline), or `""` if nothing but the
+ * block (and whitespace) remains — the caller deletes the file in that case. Pure.
+ */
+export function removeBlock(existing) {
+    const region = extractManagedRegion(existing);
+    if (region === null)
+        return existing;
+    const without = existing.replace(region, "").replace(/\n{3,}/g, "\n\n").trim();
+    return without === "" ? "" : `${without}\n`;
+}
+/** Ensure exactly one trailing newline. */
+function ensureTrailingNewline(s) {
+    return `${s.replace(/\n+$/, "")}\n`;
+}

package/dist/plan.d.ts

@@ -9,6 +9,7 @@
  */
 import type { AgentId, FileActionKind, Mode, PlannedAction, Result, Scope, InstallManifest } from "./types.js";
 import { type LocatedSource } from "./source.js";
+import { type ResolvedPlacement } from "./placements.js";
 /**
  * Everything the pure planner needs to diff source ⇆ destination ⇆ manifest for ONE agent
  * (spec 04 §4). Built by cli.ts (07); the planner reads these and writes nothing.
@@ -30,6 +31,12 @@ export interface PlanContext {
     readonly force: boolean;
     /** The pinned rauf coordinate to surface on the plan (06); the planner only echoes it. */
     readonly raufPin?: string | null;
+    /**
+     * Resolved secondary placements for this agent (A4b), or absent/empty when it has none. Supplied by
+     * cli.ts (which holds the scope roots); the planner diffs each against its destination and the prior
+     * manifest's matching placement inventory.
+     */
+    readonly placements?: ResolvedPlacement[];
 }
 /**
  * Classify one bundle-relative path (spec 04 §6 table). PURE: hashes are read, nothing is written.

package/dist/plan.js

@@ -10,7 +10,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { ok, err } from "./types.js";
-import { sha256File } from "./hash.js";
+import { sha256File, sha256String } from "./hash.js";
+import { selectMirrorFiles, renderCopilotBlock, wrapBlock, extractManagedRegion, } from "./placements.js";
 import { planUninstall } from "./manifest.js";
 import { isWindows } from "./fsutil.js";
 /**
@@ -98,15 +99,100 @@ function buildPlan(ctx, withOrphans) {
     const files = ctx.mode === "symlink"
         ? planSymlink(ctx)
         : planCopy(ctx, withOrphans);
+    // Secondary placements (A4b) are always copy-style regardless of the primary mode: a mirror is a
+    // few flat files and a managed-block is a merge, neither of which a whole-dir symlink expresses.
+    const placements = planPlacements(ctx, withOrphans);
     const action = {
         agent: ctx.agent,
         scope: ctx.scope,
         mode: ctx.mode,
         files,
         ...(ctx.raufPin !== undefined ? { raufPin: ctx.raufPin } : {}),
+        ...(placements.length > 0 ? { placements } : {}),
     };
     return ok(action);
 }
+// ---------------------------------------------------------------------------
+// Secondary placements (A4b)
+// ---------------------------------------------------------------------------
+/** Plan every resolved secondary placement (A4b). `ctx.source` is non-null here. */
+function planPlacements(ctx, withOrphans) {
+    const resolved = ctx.placements ?? [];
+    if (resolved.length === 0)
+        return [];
+    const source = ctx.source;
+    const priorByDest = priorPlacementIndex(ctx.priorManifest);
+    return resolved.map((rp) => rp.kind === "mirror"
+        ? planMirror(ctx, rp, source, priorByDest.get(rp.destination) ?? null, withOrphans)
+        : planManagedBlock(ctx, rp, source, priorByDest.get(rp.destination) ?? null));
+}
+/** Index prior-manifest placements by their absolute destination, for clean/orphan reconciliation. */
+function priorPlacementIndex(prior) {
+    const m = new Map();
+    for (const p of prior?.placements ?? [])
+        m.set(p.destination, p);
+    return m;
+}
+/** Diff a "mirror" placement: each selected bundle file vs its flat destination + recorded hash. */
+function planMirror(ctx, rp, source, prior, withOrphans) {
+    const recorded = new Map();
+    for (const f of prior?.files ?? [])
+        recorded.set(f.path, f);
+    const mirror = selectMirrorFiles(source, rp.spec);
+    const files = mirror.map((mf) => {
+        const destAbs = path.join(rp.destination, mf.destRelpath);
+        const destHash = hashIfExists(destAbs);
+        const manifestHash = recorded.get(mf.destRelpath)?.sha256;
+        const action = classifyFile(mf.destRelpath, mf.srcHash, destHash, manifestHash, ctx.force);
+        return { relpath: mf.destRelpath, action, srcRelpath: mf.srcRelpath };
+    });
+    if (withOrphans && prior !== null) {
+        const live = new Set(mirror.map((mf) => mf.destRelpath));
+        for (const f of prior.files) {
+            if (!live.has(f.path))
+                files.push({ relpath: f.path, action: "remove" });
+        }
+    }
+    return { kind: "mirror", root: rp.root, destination: rp.destination, files };
+}
+/** Diff a "managed-block" placement: render the block, compare its region to the on-disk region. */
+function planManagedBlock(ctx, rp, source, prior) {
+    const blockContent = renderCopilotBlock(source.skills);
+    const newHash = sha256String(wrapBlock(blockContent));
+    const basename = path.basename(rp.destination);
+    const current = readManagedRegionHash(rp.destination);
+    const recordedHash = prior?.files.find((f) => f.path === basename)?.sha256;
+    let action;
+    if (current === undefined) {
+        action = "create"; // no managed region present yet
+    }
+    else if (current === newHash) {
+        action = "unchanged";
+    }
+    else {
+        const clean = recordedHash !== undefined && current === recordedHash;
+        action = clean ? "overwrite" : ctx.force ? "overwrite" : "skip-modified";
+    }
+    return {
+        kind: "managed-block",
+        root: rp.root,
+        destination: rp.destination,
+        files: [{ relpath: basename, action }],
+        blockContent,
+    };
+}
+/** Hash of the managed region currently in the target file, or undefined if absent/unreadable. */
+function readManagedRegionHash(file) {
+    let content;
+    try {
+        content = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const region = extractManagedRegion(content);
+    return region === null ? undefined : sha256String(region);
+}
 /** Copy-mode per-file diff (spec 04 §6). `ctx.source` is non-null here. */
 function planCopy(ctx, withOrphans) {
     const source = ctx.source;

package/dist/rauf.d.ts

@@ -19,13 +19,13 @@ import { type Result } from "./types.js";
  *
  * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
  * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.7.0.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.8.0.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.7.0` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.8.0` resolves from the npm registry, so the
  * preflight below passes by default. (Historically this pin pointed at an unpublished package and
  * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export declare const RAUF_PIN = "@garygentry/rauf@0.7.0";
+export declare const RAUF_PIN = "@garygentry/rauf@0.8.0";
 /**
  * An injectable, READ-ONLY registry query (D1). Given a coordinate `name@version`, returns the
  * resolved version string on success, or an `InstallerError` if it is not resolvable.
@@ -37,7 +37,7 @@ export declare const RAUF_PIN = "@garygentry/rauf@0.7.0";
  * Contract: the query MUST be read-only — it MUST NOT install, MUST NOT mutate global npm
  * state, and MUST NOT execute rauf. `npm view` satisfies this (it only reads registry metadata).
  *
- * @param coordinate - the `name@version` to resolve, e.g. "@garygentry/rauf@0.7.0"
+ * @param coordinate - the `name@version` to resolve, e.g. "@garygentry/rauf@0.8.0"
  * @returns Result<string> — the resolved version on success; RAUF_UNRESOLVABLE on failure.
  */
 export type RegistryQuery = (coordinate: string) => Result<string>;

package/dist/rauf.js

@@ -20,13 +20,13 @@ import { err, ok } from "./types.js";
  *
  * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
  * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.7.0.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.8.0.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.7.0` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.8.0` resolves from the npm registry, so the
  * preflight below passes by default. (Historically this pin pointed at an unpublished package and
  * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export const RAUF_PIN = "@garygentry/rauf@0.7.0";
+export const RAUF_PIN = "@garygentry/rauf@0.8.0";
 /**
  * Resolvability preflight for the pinned default loop runner (D1; REQ-RAUF-01/02/03, OQ-1).
  *

package/dist/report.js

@@ -47,6 +47,9 @@ function renderAgent(subcommand, a) {
         // Decode the synthetic status rows (§3.3) into one human line.
         const status = a.actions.map((f) => f.relpath).join("  ");
         lines.push(`${a.agent}: ${a.detected ? "detected" : "not detected"}  ${status}`);
+        const note = confidenceNote(a);
+        if (note)
+            lines.push(`  ${note}`);
         return lines;
     }
     if (!a.ok && a.error) {
@@ -58,10 +61,28 @@ function renderAgent(subcommand, a) {
     for (const f of a.actions) {
         lines.push(`  ${actionVerb(f.action)} ${f.relpath}`);
     }
+    const note = confidenceNote(a);
+    if (note)
+        lines.push(`  ${note}`);
     if (a.raufPin)
         lines.push(`  rauf default runner pinned: ${a.raufPin}`);
     return lines;
 }
+/**
+ * Honest per-agent confidence note (A4 / Finding 6): silent for fully-trusted targets
+ * (`confirmed`/`verified-current`), explicit for `best-known`/`unsupported` so a user knows
+ * an install path may not be auto-loaded by that agent and where to check current docs. Pure.
+ */
+function confidenceNote(a) {
+    if (!a.confidence || a.confidence === "confirmed" || a.confidence === "verified-current") {
+        return null;
+    }
+    const where = a.docsUrl ? ` — see ${a.docsUrl}` : "";
+    if (a.confidence === "unsupported") {
+        return `note: ${a.agent} has no confirmed install surface (unsupported)${where}`;
+    }
+    return `note: ${a.agent} install path is best-known, not vendor-confirmed${where}`;
+}
 /** Map a FileActionKind to its human verb (REQ-OBS-01 vocabulary). */
 export function actionVerb(kind) {
     switch (kind) {

package/dist/source.d.ts

@@ -44,9 +44,10 @@ export interface LocatedSource {
 export declare function locateBundle(agent: AgentId, opts?: LocateBundleOpts): Result<string>;
 /**
  * Minimal integrity check for a located bundle (REQ-OPS-06). Valid iff the `BUNDLE_REQUIRED_PATHS`
- * are present: `skills/` is a non-empty dir, `scripts/forge-root.sh` exists, and (gemini)
- * `gemini-extension.json` exists. Does NOT require `.claude-plugin/plugin.json` or
- * `epic-manifest.py` (IR-1 / OQ-A).
+ * are present: `skills/` is a non-empty dir, the neutral `.feature-forge-bundle.json` sentinel and
+ * every bundled runtime helper (`forge-root.sh`, `forge-init.sh`, `epic-manifest.py`,
+ * `validate-traceability.py`, `forge-bootstrap.py`) exist, and (gemini) `gemini-extension.json`
+ * exists. Keys on the neutral sentinel, NOT the Claude-only `.claude-plugin/plugin.json`.
  *
  * @returns ok(undefined) when every required path is present; err(SOURCE_INVALID) naming the
  *          first missing/invalid required path otherwise.

package/dist/source.js

@@ -38,9 +38,10 @@ export function locateBundle(agent, opts = {}) {
 }
 /**
  * Minimal integrity check for a located bundle (REQ-OPS-06). Valid iff the `BUNDLE_REQUIRED_PATHS`
- * are present: `skills/` is a non-empty dir, `scripts/forge-root.sh` exists, and (gemini)
- * `gemini-extension.json` exists. Does NOT require `.claude-plugin/plugin.json` or
- * `epic-manifest.py` (IR-1 / OQ-A).
+ * are present: `skills/` is a non-empty dir, the neutral `.feature-forge-bundle.json` sentinel and
+ * every bundled runtime helper (`forge-root.sh`, `forge-init.sh`, `epic-manifest.py`,
+ * `validate-traceability.py`, `forge-bootstrap.py`) exist, and (gemini) `gemini-extension.json`
+ * exists. Keys on the neutral sentinel, NOT the Claude-only `.claude-plugin/plugin.json`.
  *
  * @returns ok(undefined) when every required path is present; err(SOURCE_INVALID) naming the
  *          first missing/invalid required path otherwise.

package/dist/types.d.ts

@@ -32,19 +32,76 @@ export declare const EXIT: {
     readonly USAGE: 2;
 };
 export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
-/** Manifest schema version; bumped only on a breaking manifest-shape change. */
-export declare const SCHEMA_VERSION: 1;
+/**
+ * Manifest schema version. v2 (A4b) adds the optional `placements[]` array for agents whose
+ * install spans a second filesystem root (codex `.codex/agents`, copilot `.github/copilot-
+ * instructions.md`). A v1 manifest (no `placements`) is still read verbatim by the back-compat
+ * reader — bumped only on a breaking manifest-shape change.
+ */
+export declare const SCHEMA_VERSION: 2;
+/** Versions of the manifest this installer can READ (write is always SCHEMA_VERSION). */
+export declare const READABLE_SCHEMA_VERSIONS: readonly [1, 2];
+/** A manifest schemaVersion this installer accepts on read (back-compat v1 + current v2). */
+export type ReadableSchemaVersion = (typeof READABLE_SCHEMA_VERSIONS)[number];
 /** The single namespace directory name written inside each agent's install location [D5]. */
 export declare const FEATURE_FORGE_NS: "feature-forge";
 /** Filename prefix for the hidden parent-sibling manifest, completed by the scope (§3, spec 05). */
 export declare const MANIFEST_PREFIX: ".feature-forge.";
+/**
+ * How honestly an agent's install paths track current vendor docs (Finding 6 / A4).
+ * - "confirmed"        — source-verified end-to-end (claude).
+ * - "verified-current" — matches the vendor's current docs, re-verified in A0 (2026-06-26).
+ * - "best-known"       — plausible but not doc-confirmed for this scope; install proceeds,
+ *                        labeled honestly in the report so users know it may not be loaded.
+ * - "unsupported"      — no usable install surface; not installed (reserved; none today).
+ */
+export type Confidence = "confirmed" | "verified-current" | "best-known" | "unsupported";
+/** How an agent consumes the bundle (documentation + future per-kind apply behavior). */
+export type InstallKind = "skills" | "extension" | "rules" | "instructions";
+/**
+ * Kind of a SECONDARY install placement (A4b). The primary bundle (the `feature-forge/` namespace
+ * dir) is always present and is never a placement; placements describe extra writes under a
+ * DIFFERENT filesystem root than the primary bundle:
+ * - "mirror"        — copy a subset of bundle files flat into a second dir (codex `.codex/agents/`,
+ *                     where Codex loads custom agents — it does not read them from `.agents/skills`).
+ * - "managed-block" — write/merge a sentinel-delimited block into a (possibly user-owned) instructions
+ *                     file (copilot `.github/copilot-instructions.md`), preserving the rest of the file.
+ */
+export type PlacementKind = "mirror" | "managed-block";
+/** HTML-comment sentinels delimiting a `managed-block` placement (mirrors rauf's convention). */
+export declare const MANAGED_BLOCK_START: "<!-- feature-forge:managed:start -->";
+export declare const MANAGED_BLOCK_END: "<!-- feature-forge:managed:end -->";
+/**
+ * Declarative descriptor of one secondary placement on an {@link AgentTarget} (A4b). Pure data, so a
+ * new agent (or a new second-root rule) stays one table edit (REQ-SCALE-01). The absolute root and
+ * destination are derived under a scope by {@link resolvePlacements}; nothing here is stored.
+ */
+export interface PlacementSpec {
+    readonly kind: PlacementKind;
+    /** Second-root dir under the scope root, e.g. ".codex" (mirror) or ".github" (managed-block). */
+    readonly baseDir: string;
+    /**
+     * Path under `baseDir`. For "mirror" this is the destination DIR (e.g. "agents"); for
+     * "managed-block" this is the target FILE (e.g. "copilot-instructions.md").
+     */
+    readonly subpath: string;
+    /**
+     * "mirror" only: bundle-relative prefix selecting which source files to copy (e.g. "agents/").
+     * Files matching the prefix are copied FLAT (basename only) into the placement destination.
+     */
+    readonly sourcePrefix?: string;
+}
 /**
  * One row of the static per-agent detection map (REQ-DET-01, REQ-DET-05). Adding a new
  * agent is exactly adding one entry to `AGENT_TARGETS` — no logic change (REQ-SCALE-01).
  *
  * The on-disk destination for an agent under a given scope is derived, not stored:
- *   <scopeRoot>/<configDirName>/<installSubdir>/<FEATURE_FORGE_NS>/
- * where scopeRoot is the resolved home (global) or cwd (project).
+ *   <scopeRoot>/<installBaseDir>/<installSubpath>/<FEATURE_FORGE_NS>/
+ * where scopeRoot is the resolved home (global) or cwd (project), and `installSubpath` may
+ * be "" (installed directly under `installBaseDir`). Detection (`configDirName`) is decoupled
+ * from the install location because some agents load content from a different tree than the
+ * dir that signals their presence (A4): codex detects ".codex" but loads skills from
+ * ".agents/skills"; copilot detects ".copilot" but instructions live under ".github".
  */
 export interface AgentTarget {
     /** Stable agent identifier. */
@@ -55,22 +112,36 @@ export interface AgentTarget {
      */
     readonly configDirName: string;
     /**
-     * Sub-path under the config dir that holds the namespaced install dir, e.g.
-     * "skills" (claude/codex/copilot), "rules" (cursor), "extensions" (gemini).
+     * Top-level dir under the scope root that holds the install AND is the containment boundary
+     * every write is checked against (REQ-SEC-02). Usually equals `configDirName`; decoupled for
+     * codex (".agents") and copilot (".github").
+     */
+    readonly installBaseDir: string;
+    /**
+     * Path under `installBaseDir` to the namespace parent, e.g. "skills" (claude/codex),
+     * "rules" (cursor), "extensions" (gemini), "" (copilot — directly under `.github`).
      */
-    readonly installSubdir: string;
+    readonly installSubpath: string;
+    /** How this agent consumes the bundle (REQ-SCALE-01; per-kind placement extended in A4b). */
+    readonly installKind: InstallKind;
     /**
-     * Informational: the skill-file form this agent's bundle uses — "SKILL.md" (claude),
-     * "<name>.md" (codex/copilot/gemini), "<name>.mdc" (cursor). The installer copies the
+     * Informational: the skill-file form this agent's bundle uses — "SKILL.md" (claude, codex),
+     * "<name>.md" (copilot/gemini), "<name>.mdc" (cursor). The installer copies the
      * bundle verbatim (REQ-SCALE-02) and does not parse skill files, so this is documentation.
      */
     readonly skillFileForm: string;
+    /** Confidence for the default (global) scope. */
+    readonly confidence: Confidence;
+    /** Optional scope-specific override for project scope (e.g. gemini project = best-known). */
+    readonly projectConfidence?: Confidence;
+    /** Current vendor/docs URL for this target's install convention (surfaced in reports). */
+    readonly docsUrl: string;
     /**
-     * Confidence in this row's paths. "confirmed" = source-verified (claude). "best-known"
-     * = the TQ-1 paths (codex/copilot/cursor/gemini) to re-verify against each agent's current
-     * docs at implementation (REQ-SCALE-01 — isolated, localized correction).
+     * Secondary install placements under a DIFFERENT root than the primary bundle (A4b). Absent for
+     * agents whose whole install is the single namespace dir (claude/cursor/gemini). Declarative data
+     * only — resolved to absolute roots by {@link resolvePlacements}; a new rule is one table edit.
      */
-    readonly confidence: "confirmed" | "best-known";
+    readonly placements?: readonly PlacementSpec[];
 }
 /** Options for path resolution, injectable so tests never touch the real `~` (spec 02, spec 08). */
 export interface ResolveOpts {
@@ -95,6 +166,10 @@ export interface DetectionResult {
     readonly cliOnPath?: boolean;
     /** Resolved absolute install destination for the active scope (the `feature-forge/` namespace dir). */
     readonly destination: string;
+    /** Effective confidence for the active scope (REQ-DET-05; honest dry-run/list labeling, A4). */
+    readonly confidence: Confidence;
+    /** Current vendor/docs URL for this target (REQ-DET-05). */
+    readonly docsUrl: string;
 }
 /** One file recorded in the manifest inventory (REQ-SAFE-01). */
 export interface ManifestFile {
@@ -103,13 +178,30 @@ export interface ManifestFile {
     /** SHA-256 of the written bytes. Omitted for symlink mode (no per-file copy exists). */
     readonly sha256?: string;
 }
+/**
+ * One persisted SECONDARY placement (manifest v2, A4b). Records the absolute second root + dest and
+ * an inventory of what we wrote there, so `update`/`uninstall` reconcile it exactly like the primary
+ * bundle but under its own containment boundary (`root`). For "managed-block", `files` holds a single
+ * entry whose `path` is the file basename and whose `sha256` fingerprints the block region we wrote
+ * (drift/clean detection); the rest of that file is user-owned and never recorded.
+ */
+export interface Placement {
+    readonly kind: PlacementKind;
+    /** Absolute containment boundary every write for this placement is checked against (REQ-SEC-02). */
+    readonly root: string;
+    /** Absolute destination: a DIR ("mirror") or a FILE ("managed-block"). */
+    readonly destination: string;
+    /** Per-file inventory written under this placement (paths relative to `destination`'s dir). */
+    readonly files: ManifestFile[];
+}
 /**
  * The persisted per-install manifest (REQ-SAFE-01/03), written as the hidden parent-sibling
  * `<installSubdir>/.feature-forge.<scope>.json` (spec 05). It is the sole record `list`/`update`/
  * `uninstall` use to tell installer-written content from user content and to detect drift.
  */
 export interface InstallManifest {
-    readonly schemaVersion: typeof SCHEMA_VERSION;
+    /** Always {@link SCHEMA_VERSION} when written; v1 is still accepted on read (back-compat). */
+    readonly schemaVersion: ReadableSchemaVersion;
     readonly agent: AgentId;
     readonly scope: Scope;
     readonly mode: Mode;
@@ -124,7 +216,7 @@ export interface InstallManifest {
     readonly featureForgeVersion: string | null;
     /** SHA-256 over the source bundle's canonical (sorted-path) file set — drift anchor (OQ-4, spec 03). */
     readonly sourceHash: string;
-    /** Pinned rauf coordinate recorded at install, e.g. "@garygentry/rauf@0.7.0"; `null` if `--skip-rauf` (spec 06). */
+    /** Pinned rauf coordinate recorded at install, e.g. "@garygentry/rauf@0.8.0"; `null` if `--skip-rauf` (spec 06). */
     readonly raufPin: string | null;
     /** ISO-8601 timestamps. */
     readonly installedAt: string;
@@ -137,6 +229,11 @@ export interface InstallManifest {
     readonly link?: {
         readonly target: string;
     };
+    /**
+     * Secondary placements written under a different root than the primary bundle (manifest v2, A4b).
+     * Absent on agents without a second-root rule (claude/cursor/gemini) and on legacy v1 manifests.
+     */
+    readonly placements?: Placement[];
 }
 /**
  * The per-file action the planner assigns by diffing source ⇆ destination ⇆ manifest (spec 04).
@@ -165,6 +262,36 @@ export interface PlannedAction {
     readonly files: FileAction[];
     /** Surfaced in the plan/report for visibility (spec 06); not a file action. */
     readonly raufPin?: string | null;
+    /**
+     * Resolved secondary-placement plans (A4b). Each carries its own absolute root + destination, the
+     * per-file diff actions, and (for "managed-block") the exact block content a real run will write —
+     * so dry-run shows, and `apply` performs, identical work. Absent when the agent has no placements.
+     */
+    readonly placements?: PlannedPlacement[];
+}
+/**
+ * One secondary placement's resolved plan (A4b): the dry-run = real-run unit for a second root. The
+ * planner fills `files` by diffing source ⇆ destination (same classifier as the primary bundle) and,
+ * for "managed-block", attaches the rendered `blockContent` the apply step writes between sentinels.
+ */
+export interface PlannedPlacement {
+    readonly kind: PlacementKind;
+    /** Absolute containment boundary (REQ-SEC-02). */
+    readonly root: string;
+    /** Absolute destination dir ("mirror") or file ("managed-block"). */
+    readonly destination: string;
+    /**
+     * Per-file diff actions. "mirror" entries carry `srcRelpath` (the bundle-relative source to copy);
+     * "managed-block" has a single entry whose `relpath` is the file basename (no `srcRelpath`).
+     */
+    readonly files: PlacementFileAction[];
+    /** "managed-block" only: the rendered block body (without sentinels) a create/overwrite writes. */
+    readonly blockContent?: string;
+}
+/** A placement file action: a {@link FileAction} plus the bundle-relative source for "mirror" copies. */
+export interface PlacementFileAction extends FileAction {
+    /** "mirror" only: bundle-relative source path to copy into `<destination>/<relpath>`. */
+    readonly srcRelpath?: string;
 }
 /** One agent's outcome in a run summary (REQ-OBS-01/03). */
 export interface AgentReport {
@@ -177,6 +304,10 @@ export interface AgentReport {
     /** Present iff `ok` is false. */
     readonly error?: InstallerError;
     readonly raufPin?: string | null;
+    /** Effective install-path confidence for the active scope (A4; honest report labeling). */
+    readonly confidence?: Confidence;
+    /** Vendor/docs URL for this target (A4; shown when confidence is not full). */
+    readonly docsUrl?: string;
 }
 /** The whole-run summary, rendered human-readable or as `--json` (REQ-OBS-01, REQ-DET-05). */
 export interface RunReport {
@@ -205,17 +336,30 @@ export interface RunReport {
  *
  * Verified ground truth: every bundle has `skills/` (11 skills), `references/`,
  * `scripts/forge-root.sh`, `agents/`; gemini adds a root `gemini-extension.json`,
- * codex adds `agents/openai.yaml`, cursor uses `.mdc` files.
+ * codex ships `skills/<name>/SKILL.md` + standalone `agents/<name>.toml` custom agents,
+ * cursor uses `.mdc` files.
+ *
+ * A4 per-agent reality check (A0 re-verified vendor docs, 2026-06-26):
+ *  - codex   — detects `.codex`, loads skills from `.agents/skills` (verified-current).
+ *              The `.codex/agents/*.toml` second placement is added in A4b.
+ *  - copilot — detects `.copilot`, but has no skills loader; the bundle is staged under
+ *              `.github/feature-forge` and the managed instructions block (.github/
+ *              copilot-instructions.md) is added in A4b (best-known).
+ *  - cursor  — `.cursor/rules/*.mdc` confirmed current (verified-current).
+ *  - gemini  — `~/.gemini/extensions/feature-forge` global confirmed; project scope is
+ *              best-known (project extension install is not clearly documented).
  */
 export declare const AGENT_TARGETS: Readonly<Record<AgentId, AgentTarget>>;
 /**
  * Minimal integrity check (REQ-OPS-06, spec 03): a located bundle is valid iff `skills/` is a
- * non-empty dir, `scripts/forge-root.sh` exists, and — for gemini only — `gemini-extension.json`
- * exists at the bundle root. Defined here as data so the check is a localized table read.
+ * non-empty dir, the neutral bundle sentinel `.feature-forge-bundle.json` exists, every runtime
+ * helper script a skill can invoke is present (so helper-backed skills run after install on ANY
+ * agent), and — for gemini only — `gemini-extension.json` exists at the bundle root. Defined here
+ * as data so the check is a localized table read.
  */
 export declare const BUNDLE_REQUIRED_PATHS: {
     /** Required of every agent bundle. */
-    readonly common: readonly ["skills", "scripts/forge-root.sh"];
+    readonly common: readonly ["skills", ".feature-forge-bundle.json", "scripts/forge-root.sh", "scripts/forge-init.sh", "scripts/epic-manifest.py", "scripts/validate-traceability.py", "scripts/forge-bootstrap.py"];
     /** Additional per-agent requirements. */
     readonly perAgent: Partial<Record<AgentId, readonly string[]>>;
 };