@productbrain/cli 0.1.0-beta.5 → 0.1.0-beta.5060

package/README.md

@@ -1,59 +1,129 @@
 # Product Brain CLI (`pb`)
 
-Read-only CLI for Chain knowledge: orient, search, get entry, gather context. Uses your Product Brain API key (same as MCP).
+Chain knowledge + write-back in the terminal. Read, search, capture, and update your product knowledge graph.
 
-**Requirements:** Node 18+, API key from Product Brain → Settings → API Keys (`pb_sk_*`).
-
----
+**Requirements:** Node 18+, API key from Product Brain Settings (`pb_sk_*`).
 
 ## Install
 
-### From npm (beta)
-
 ```bash
 npm install -g @productbrain/cli@beta
 ```
 
-Updates require a new publish to npm (and, if you use 2FA, a one-time password). Use this when you want a stable beta from the registry.
-
-### From main (no publish needed)
-
-If you have the repo and want **latest from `main`** without publishing to npm:
+From source (latest main):
 
 ```bash
 git clone https://github.com/synergyai-os/Product-OS.git
-cd Product-OS
-npm ci
+cd Product-OS && npm ci
 cd packages/cli && npm run build && npm install -g .
 ```
 
-After that, `pb` runs from your global path. Pull and re-run the last two commands to update:
+## Login
 
 ```bash
-cd Product-OS && git pull && cd packages/cli && npm run build && npm install -g .
+pb login
 ```
 
-See [Deployment strategy — CLI vs MCP](../../docs/deployment-strategy.md#cli-vs-mcp-distribution) for why this avoids `cli:publish` / OTP.
+Paste your API key (`pb_sk_...`). Saved to `~/.config/productbrain/.env`.
 
----
+Or run any command without a key and follow the guided flow.
 
-## First run
+### Onboarding link (`pb connect`)
 
-- **No key yet:** Run any command (e.g. `pb orient -b`). You’ll get a short guided flow: “Do you have an API key? (y/n)” → paste key → saved to `~/.config/productbrain/.env`. Your command then runs.
-- **Or:** Run `pb login` to paste and save your key once. Get a key: Product Brain app → Settings → API Keys.
+If you received a connect token (`pb_ct_...`) from Product Brain:
 
-Config is read from (in order): env vars → `~/.config/productbrain/.env` → `.env.mcp` in the current directory.
+```bash
+pb connect pb_ct_...
+```
+
+Redemption always targets a cloud Convex deployment (HTTP Actions are cloud-hosted, even during local dev). Resolution order: `--gateway` → `PB_CONNECT_GATEWAY_URL` → `CONVEX_SITE_URL` → production default (`gateway.productbrain.io`).
 
----
+- **Dev deployments:** Set `CONVEX_SITE_URL` to your `*.convex.site` URL, or use `--gateway`.
+- If a token fails, the CLI hints about setting `CONVEX_SITE_URL` or using `--gateway`.
+
+## Quick Start
+
+```bash
+# 1. Check your setup
+pb doctor
+
+# 2. Orient — see where things stand
+pb orient -b
+
+# 3. Read an entry
+pb get BET-123
+
+# 4. Search the Chain
+pb search "onboarding flow"
+
+# 5. Start a write session and capture knowledge
+pb session start
+pb capture "DEC: chose X because Y"
+pb capture "TEN: blocked by missing API"
+pb session close
+```
+
+Running `pb` with no arguments shows contextual guidance based on your setup state.
 
 ## Commands
 
+### Read (no session required)
+
 | Command | Description |
-|--------|-------------|
-| `pb orient` | Workspace stage, bets, governance, tensions. Use `-b` for a brief view. |
-| `pb search <query>` | Full-text search across the Chain. |
-| `pb get <entry-id>` | Full entry (data, relations, last 10 history events). |
-| `pb context <entry-id>` | Constellation context (pipe-friendly markdown when not a TTY). |
-| `pb login` | Save your API key to `~/.config/productbrain/.env`. |
-
-`pb --help` for options.
+|---------|-------------|
+| `pb orient [-b]` | Workspace overview. `-b` for brief, `--task` for task-grounded context. |
+| `pb get <id>` | Full entry: data, relations, history. |
+| `pb search <query>` | Full-text search across all collections. |
+| `pb context <id>` | Constellation context for an entry. |
+| `pb fields <collection>` | Field definitions for a collection. |
+| `pb constellation <id>` | Entry + all related entries grouped by relation type. |
+| `pb collections list` | All collections with field counts. |
+| `pb glossary` | Key Product Brain CLI terms. |
+| `pb scoreboard [--task <task>] [--json]` | Flywheel health board: M1/M2/M3 metrics, materialization age, and diagnosis. `--json` for the structured agent shape. |
+| `pb doctor` | Check configuration and connectivity. |
+
+### Write (session required)
+
+| Command | Description |
+|---------|-------------|
+| `pb session start` | Open a tracked write session. |
+| `pb capture "<text>"` | Capture knowledge. Auto-classifies to the right collection. |
+| `pb update <id>` | Update fields on an existing entry. |
+| `pb relate <from> <type> <to>` | Add a typed relation between entries. |
+| `pb entry accept <id>` | Accept a draft entry onto the Chain (commit to SSOT). |
+| `pb entry archive <id> --reason <reason>` | Archive an entry with a DEC-1572 reason. |
+| `pb session close` | Close session, show summary. |
+
+### Profile Management
+
+Config is read from (in order): environment variables, `~/.config/productbrain/.env`, `.env.mcp` in the current directory.
+
+```bash
+pb login          # Save API key
+pb doctor         # Verify configuration
+pb setup          # Guided first-time setup
+```
+
+### AI Developer Onboarding
+
+```bash
+pb handshake      # Generate context files for Codex, Cursor, Claude, Copilot
+```
+
+Generates `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/chain.mdc`, `.productbrain/context.md`, and more.
+
+## Output Modes
+
+| Context | Output |
+|---------|--------|
+| TTY (terminal) | Human-readable formatting |
+| Piped / non-TTY | JSON |
+| `--json` | Force JSON |
+| `--pretty` | Force human-readable |
+
+## Reference
+
+- `pb --help` for full command list
+- `pb <command> --help` for command-specific options
+- `pb glossary` for key terms
+- Chain: WP-302 (CLI Maturity)

package/dist/__tests__/adapters.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapters.test.d.ts.map

package/dist/__tests__/adapters.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/adapters.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/adapters.test.js

@@ -0,0 +1,470 @@
+/**
+ * adapters — unit tests for generateAgentsMd and generateCopilotMd.
+ * BET-270 Slice 2: governance-enriched AGENTS.md adapter.
+ * BET-270 Slice 3: profile-driven single-file Copilot adapter.
+ */
+import { describe, expect, it } from 'vitest';
+import { MARKER, generateAgentsMd, generateCopilotMd, generateCopilotInstructionFiles } from '../generators/adapters.js';
+import { SURFACE_PROFILES } from '../generators/surface-profiles.js';
+const TIMESTAMP = '2026-04-05T12:00:00.000Z';
+// ── Auto-generated marker ─────────────────────────────────────────────
+describe('generateAgentsMd — marker', () => {
+    it('always includes the auto-generated marker', () => {
+        expect(generateAgentsMd(TIMESTAMP)).toContain(MARKER);
+    });
+    it('always includes the marker when options are provided', () => {
+        expect(generateAgentsMd(TIMESTAMP, {
+            workspaceContext: { stage: 'grounded' },
+            skills: [{ name: 'my-skill', description: 'does things' }],
+        })).toContain(MARKER);
+    });
+    it('embeds the timestamp in the marker line', () => {
+        const result = generateAgentsMd(TIMESTAMP);
+        expect(result).toContain(`<!-- ${MARKER} — ${TIMESTAMP} -->`);
+    });
+});
+// ── Backward compatibility (no options) ──────────────────────────────
+describe('generateAgentsMd — no options (backward compat)', () => {
+    it('produces the command reference table', () => {
+        const result = generateAgentsMd(TIMESTAMP);
+        expect(result).toContain('pb orient -b');
+        expect(result).toContain('pb get <ID>');
+        expect(result).toContain('pb search <query>');
+        expect(result).toContain('pb handshake');
+    });
+    it('produces the session lifecycle section', () => {
+        const result = generateAgentsMd(TIMESTAMP);
+        expect(result).toContain('pb session start');
+        expect(result).toContain('pb capture');
+        expect(result).toContain('pb session close');
+    });
+    it('does not include workspace context section when no options given', () => {
+        const result = generateAgentsMd(TIMESTAMP);
+        expect(result).not.toContain('## Workspace Context');
+    });
+    it('does not include skill directory when no options given', () => {
+        const result = generateAgentsMd(TIMESTAMP);
+        expect(result).not.toContain('## Skill Directory');
+    });
+    it('includes governance summary', () => {
+        const result = generateAgentsMd(TIMESTAMP);
+        expect(result).toContain('## Governance Summary');
+    });
+});
+// ── Workspace Context section ─────────────────────────────────────────
+describe('generateAgentsMd — workspaceContext', () => {
+    it('includes workspace context section when workspaceContext is provided', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            workspaceContext: { stage: 'grounded', governanceMode: 'active', totalEntries: 42 },
+        });
+        expect(result).toContain('## Workspace Context');
+    });
+    it('renders stage in workspace context table', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            workspaceContext: { stage: 'grounded' },
+        });
+        expect(result).toContain('grounded');
+        expect(result).toContain('Stage');
+    });
+    it('renders focus in workspace context table', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            workspaceContext: { focus: 'Ship BET-270' },
+        });
+        expect(result).toContain('Ship BET-270');
+        expect(result).toContain('Current focus');
+    });
+    it('renders governanceMode in workspace context table', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            workspaceContext: { governanceMode: 'structured' },
+        });
+        expect(result).toContain('structured');
+        expect(result).toContain('Governance mode');
+    });
+    it('renders totalEntries in workspace context table', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            workspaceContext: { totalEntries: 99 },
+        });
+        expect(result).toContain('99');
+        expect(result).toContain('Chain entries');
+    });
+    it('omits workspace context section when workspaceContext is undefined', () => {
+        const result = generateAgentsMd(TIMESTAMP, { skills: [] });
+        expect(result).not.toContain('## Workspace Context');
+    });
+    it('omits workspace context section when workspaceContext is empty object', () => {
+        const result = generateAgentsMd(TIMESTAMP, { workspaceContext: {} });
+        expect(result).not.toContain('## Workspace Context');
+    });
+    it('omits skill directory when only workspaceContext provided (no skills)', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            workspaceContext: { stage: 'grounded' },
+        });
+        expect(result).not.toContain('## Skill Directory');
+    });
+});
+// ── Skill Directory section ───────────────────────────────────────────
+describe('generateAgentsMd — skills', () => {
+    it('includes skill directory when skills array provided', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            skills: [{ name: 'my-skill', description: 'does things' }],
+        });
+        expect(result).toContain('## Skill Directory');
+    });
+    it('renders skill name in the table', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            skills: [{ name: 'commit', description: 'commit changes to main' }],
+        });
+        expect(result).toContain('commit');
+        expect(result).toContain('commit changes to main');
+    });
+    it('renders skill triggers (up to 3) in the table', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            skills: [
+                {
+                    name: 'review',
+                    description: 'review changes',
+                    triggers: ['review', 'implementation review', 'review this'],
+                },
+            ],
+        });
+        expect(result).toContain('review');
+        expect(result).toContain('implementation review');
+        expect(result).toContain('review this');
+    });
+    it('caps triggers at 3 items', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            skills: [
+                {
+                    name: 'shape',
+                    description: 'shape a bet',
+                    triggers: ['shape', 'shape this', 'shape a bet', 'shape up', 'let\'s shape'],
+                },
+            ],
+        });
+        // Should have at most 3 triggers shown — 4th and 5th should not appear if they are unique
+        // The row should contain up to 3 triggers joined by ', '
+        const lines = result.split('\n');
+        const skillRow = lines.find((l) => l.includes('shape') && l.includes('shape a bet'));
+        expect(skillRow).toBeDefined();
+        const parts = skillRow.split('|');
+        // triggers cell is the 4th column (index 3)
+        const triggersCell = parts[3]?.trim() ?? '';
+        const triggerCount = triggersCell.split(',').length;
+        expect(triggerCount).toBeLessThanOrEqual(3);
+    });
+    it('renders "—" when no triggers provided for a skill', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            skills: [{ name: 'my-skill', description: 'does things' }],
+        });
+        expect(result).toContain('—');
+    });
+    it('renders multiple skills as separate rows', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            skills: [
+                { name: 'skill-a', description: 'skill A description' },
+                { name: 'skill-b', description: 'skill B description' },
+            ],
+        });
+        expect(result).toContain('skill-a');
+        expect(result).toContain('skill-b');
+        expect(result).toContain('skill A description');
+        expect(result).toContain('skill B description');
+    });
+    it('omits skill directory when skills array is empty', () => {
+        const result = generateAgentsMd(TIMESTAMP, { skills: [] });
+        expect(result).not.toContain('## Skill Directory');
+    });
+    it('omits skill directory when skills option is undefined', () => {
+        const result = generateAgentsMd(TIMESTAMP, { workspaceContext: { stage: 'grounded' } });
+        expect(result).not.toContain('## Skill Directory');
+    });
+    it('includes workspace context AND skill directory together', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            workspaceContext: { stage: 'grounded', totalEntries: 10 },
+            skills: [{ name: 'orient', description: 'orient the workspace' }],
+        });
+        expect(result).toContain('## Workspace Context');
+        expect(result).toContain('## Skill Directory');
+    });
+});
+// ── Governance summary (always present) ─────────────────────────────
+describe('generateAgentsMd — governance summary', () => {
+    it('is present with no options', () => {
+        expect(generateAgentsMd(TIMESTAMP)).toContain('## Governance Summary');
+    });
+    it('is present with full context', () => {
+        const result = generateAgentsMd(TIMESTAMP, {
+            workspaceContext: { stage: 'grounded' },
+            skills: [{ name: 'commit', description: 'commit to main' }],
+        });
+        expect(result).toContain('## Governance Summary');
+    });
+    it('mentions Product Brain governance', () => {
+        const result = generateAgentsMd(TIMESTAMP);
+        expect(result).toContain('Product Brain governance');
+    });
+});
+// ────────────────────────────────────────────────────────────────────
+// generateCopilotMd
+// ────────────────────────────────────────────────────────────────────
+// ── Marker always present ────────────────────────────────────────────
+describe('generateCopilotMd — marker', () => {
+    it('always includes the auto-generated marker with no options', () => {
+        expect(generateCopilotMd(TIMESTAMP)).toContain(MARKER);
+    });
+    it('always includes the marker when options are provided', () => {
+        expect(generateCopilotMd(TIMESTAMP, {
+            skills: [{ name: 'my-skill', description: 'does things' }],
+        })).toContain(MARKER);
+    });
+    it('embeds the timestamp in the marker line', () => {
+        const result = generateCopilotMd(TIMESTAMP);
+        expect(result).toContain(`<!-- ${MARKER} — ${TIMESTAMP} -->`);
+    });
+});
+// ── Backward compatibility (no options) ─────────────────────────────
+describe('generateCopilotMd — no options (backward compat)', () => {
+    it('produces the command reference section', () => {
+        const result = generateCopilotMd(TIMESTAMP);
+        expect(result).toContain('pb orient -b');
+        expect(result).toContain('pb get <ID>');
+        expect(result).toContain('pb search <query>');
+        expect(result).toContain('pb handshake');
+    });
+    it('produces the session lifecycle section', () => {
+        const result = generateCopilotMd(TIMESTAMP);
+        expect(result).toContain('pb session start');
+        expect(result).toContain('pb capture');
+        expect(result).toContain('pb session close');
+    });
+    it('does not include Skills section when no options given', () => {
+        const result = generateCopilotMd(TIMESTAMP);
+        expect(result).not.toContain('## Skills');
+    });
+    it('does not include Rules section when no options given', () => {
+        const result = generateCopilotMd(TIMESTAMP);
+        expect(result).not.toContain('## Rules');
+    });
+    it('does not include workspace context section when no options given', () => {
+        const result = generateCopilotMd(TIMESTAMP);
+        expect(result).not.toContain('## Workspace Context');
+    });
+});
+// ── Full context ─────────────────────────────────────────────────────
+describe('generateCopilotMd — full context', () => {
+    it('produces all sections when all options provided', () => {
+        const result = generateCopilotMd(TIMESTAMP, {
+            profile: SURFACE_PROFILES.copilot,
+            workspaceContext: { stage: 'grounded', focus: 'Ship BET-270', governanceMode: 'active', totalEntries: 55 },
+            skills: [{ name: 'commit', description: 'commit changes', triggers: ['commit'] }],
+            rules: [{ name: 'git-workflow', description: 'two-track git workflow' }],
+        });
+        expect(result).toContain('## Workspace Context');
+        expect(result).toContain('## Skills');
+        expect(result).toContain('## Rules');
+        expect(result).toContain('commit');
+        expect(result).toContain('git-workflow');
+    });
+    it('renders workspace context fields', () => {
+        const result = generateCopilotMd(TIMESTAMP, {
+            workspaceContext: { stage: 'grounded', governanceMode: 'active', totalEntries: 42, focus: 'BET-270' },
+        });
+        expect(result).toContain('grounded');
+        expect(result).toContain('active');
+        expect(result).toContain('42');
+        expect(result).toContain('BET-270');
+    });
+    it('renders skill name and description', () => {
+        const result = generateCopilotMd(TIMESTAMP, {
+            skills: [{ name: 'review', description: 'review implementation changes' }],
+        });
+        expect(result).toContain('### review');
+        expect(result).toContain('review implementation changes');
+    });
+    it('renders skill triggers (up to 3)', () => {
+        const result = generateCopilotMd(TIMESTAMP, {
+            skills: [
+                { name: 'shape', description: 'shape a bet', triggers: ['shape', 'shape this', 'shape a bet', 'let\'s shape'] },
+            ],
+        });
+        expect(result).toContain('shape');
+        expect(result).toContain('shape this');
+        expect(result).toContain('shape a bet');
+        // 4th trigger should not appear as it was sliced
+        expect(result).not.toContain('let\'s shape');
+    });
+    it('renders rule name and description', () => {
+        const result = generateCopilotMd(TIMESTAMP, {
+            rules: [{ name: 'feature-flags', description: 'three-tier feature flag resolution' }],
+        });
+        expect(result).toContain('### feature-flags');
+        expect(result).toContain('three-tier feature flag resolution');
+    });
+    it('renders multiple skills as separate headings', () => {
+        const result = generateCopilotMd(TIMESTAMP, {
+            skills: [
+                { name: 'skill-a', description: 'alpha skill' },
+                { name: 'skill-b', description: 'beta skill' },
+            ],
+        });
+        expect(result).toContain('### skill-a');
+        expect(result).toContain('### skill-b');
+        expect(result).toContain('alpha skill');
+        expect(result).toContain('beta skill');
+    });
+    it('renders multiple rules as separate headings', () => {
+        const result = generateCopilotMd(TIMESTAMP, {
+            rules: [
+                { name: 'rule-one', description: 'first rule' },
+                { name: 'rule-two', description: 'second rule' },
+            ],
+        });
+        expect(result).toContain('### rule-one');
+        expect(result).toContain('### rule-two');
+    });
+    it('does not include skill bodies — only summaries', () => {
+        // Summaries contain just name + description + optional triggers, no full markdown content
+        const result = generateCopilotMd(TIMESTAMP, {
+            skills: [{ name: 'orchestrate', description: 'run bounded implementation slices' }],
+        });
+        // Should have a heading and description but NOT multi-paragraph content from the skill body
+        expect(result).toContain('### orchestrate');
+        expect(result).toContain('run bounded implementation slices');
+        // Confirm no "Run Contract" section from skill body is present
+        expect(result).not.toContain('## Run Contract');
+    });
+});
+// ── Token budget enforcement ─────────────────────────────────────────
+describe('generateCopilotMd — token budget enforcement', () => {
+    it('output length does not exceed profile token budget', () => {
+        const profile = SURFACE_PROFILES.copilot; // 30000 chars
+        // Generate a large payload
+        const manySkills = Array.from({ length: 100 }, (_, i) => ({
+            name: `skill-${i}`,
+            description: `Description for skill ${i} — a moderately long description to consume budget`,
+            triggers: [`trigger-${i}-a`, `trigger-${i}-b`, `trigger-${i}-c`],
+        }));
+        const manyRules = Array.from({ length: 50 }, (_, i) => ({
+            name: `rule-${i}`,
+            description: `Description for rule ${i} — another moderately long description`,
+        }));
+        const result = generateCopilotMd(TIMESTAMP, { profile, skills: manySkills, rules: manyRules });
+        expect(result.length).toBeLessThanOrEqual(profile.tokenBudget);
+    });
+    it('includes a truncation note when content is truncated', () => {
+        const profile = { ...SURFACE_PROFILES.copilot, tokenBudget: 2000 };
+        const manySkills = Array.from({ length: 50 }, (_, i) => ({
+            name: `skill-${i}`,
+            description: `Description for skill ${i}`,
+        }));
+        const result = generateCopilotMd(TIMESTAMP, { profile, skills: manySkills });
+        expect(result).toContain('Truncated');
+        expect(result).toContain('token budget');
+    });
+    it('does not include a truncation note when everything fits', () => {
+        const result = generateCopilotMd(TIMESTAMP, {
+            profile: SURFACE_PROFILES.copilot,
+            skills: [{ name: 'one-skill', description: 'a single skill that easily fits' }],
+            rules: [{ name: 'one-rule', description: 'a single rule that easily fits' }],
+        });
+        expect(result).not.toContain('Truncated');
+    });
+    it('respects a custom small token budget', () => {
+        // Budget must be larger than the base template (~1437 chars) + truncation note (~80 chars)
+        const smallBudget = 2500;
+        const profile = { ...SURFACE_PROFILES.copilot, tokenBudget: smallBudget };
+        const manySkills = Array.from({ length: 30 }, (_, i) => ({
+            name: `skill-${i}`,
+            description: `Description for skill ${i} with enough text to consume budget`,
+            triggers: [`trigger-${i}`],
+        }));
+        const result = generateCopilotMd(TIMESTAMP, { profile, skills: manySkills });
+        expect(result.length).toBeLessThanOrEqual(smallBudget);
+        expect(result).toContain('Truncated');
+    });
+    it('stays within budget even when base nearly fills it', () => {
+        // Budget barely above base template — should not exceed budget
+        const tightBudget = 1500;
+        const profile = { ...SURFACE_PROFILES.copilot, tokenBudget: tightBudget };
+        const manySkills = Array.from({ length: 20 }, (_, i) => ({
+            name: `skill-${i}`,
+            description: `Description ${i}`,
+        }));
+        const result = generateCopilotMd(TIMESTAMP, { profile, skills: manySkills });
+        expect(result.length).toBeLessThanOrEqual(tightBudget);
+    });
+    it('respects a large custom token budget without unnecessary truncation', () => {
+        const largeBudget = 200000;
+        const profile = { ...SURFACE_PROFILES.copilot, tokenBudget: largeBudget };
+        const fewSkills = Array.from({ length: 5 }, (_, i) => ({
+            name: `skill-${i}`,
+            description: `Short desc ${i}`,
+        }));
+        const result = generateCopilotMd(TIMESTAMP, { profile, skills: fewSkills });
+        expect(result.length).toBeLessThanOrEqual(largeBudget);
+        expect(result).not.toContain('Truncated');
+    });
+    it('truncated output still contains the marker', () => {
+        const profile = { ...SURFACE_PROFILES.copilot, tokenBudget: 2000 };
+        const manySkills = Array.from({ length: 50 }, (_, i) => ({
+            name: `skill-${i}`,
+            description: `Description for skill ${i}`,
+        }));
+        const result = generateCopilotMd(TIMESTAMP, { profile, skills: manySkills });
+        expect(result).toContain(MARKER);
+    });
+});
+// ── Path-scoped Copilot instruction files (DEC-1343) ──────────────────────
+describe('generateCopilotInstructionFiles', () => {
+    const rule = {
+        name: 'Security Boundaries',
+        applyTo: 'convex/**/*.ts',
+        body: 'Derive identity from the server auth context.\nScope every read by workspaceId at the index level.',
+        sourcePath: 'db:STD-265',
+    };
+    it('emits one file per scoped rule at .github/instructions/<slug>.instructions.md', () => {
+        const files = generateCopilotInstructionFiles([rule], TIMESTAMP);
+        expect(files).toHaveLength(1);
+        expect(files[0].relativePath).toBe('.github/instructions/security-boundaries.instructions.md');
+    });
+    it('writes the applyTo glob into frontmatter', () => {
+        const [file] = generateCopilotInstructionFiles([rule], TIMESTAMP);
+        expect(file.content).toMatch(/^---\napplyTo: "convex\/\*\*\/\*\.ts"\n---/);
+    });
+    it('inlines the FULL rule body, not a summary', () => {
+        const [file] = generateCopilotInstructionFiles([rule], TIMESTAMP);
+        expect(file.content).toContain('Scope every read by workspaceId at the index level.');
+    });
+    it('carries the pb-handshake MARKER so handshake recognises it as managed', () => {
+        const [file] = generateCopilotInstructionFiles([rule], TIMESTAMP);
+        expect(file.content).toContain(MARKER);
+    });
+    it('records provenance as a reference-only breadcrumb (pb-blind consumer)', () => {
+        const [file] = generateCopilotInstructionFiles([rule], TIMESTAMP);
+        expect(file.content).toContain('<!-- source: db:STD-265 -->');
+    });
+    it('reduces a filesystem sourcePath to its basename — POSIX and Windows', () => {
+        const [posix] = generateCopilotInstructionFiles([{ name: 'Posix', applyTo: 'a/**', body: 'x', sourcePath: '/Users/x/.productbrain/rules/security-boundaries.md' }], TIMESTAMP);
+        expect(posix.content).toContain('<!-- source: security-boundaries.md -->');
+        // A Windows authoring host yields backslash paths; splitting on '/' alone would leak the
+        // whole absolute path into committed provenance (finding #7).
+        const [win] = generateCopilotInstructionFiles([{ name: 'Win', applyTo: 'b/**', body: 'y', sourcePath: 'C:\\Users\\x\\.productbrain\\rules\\security-boundaries.md' }], TIMESTAMP);
+        expect(win.content).toContain('<!-- source: security-boundaries.md -->');
+        expect(win.content).not.toContain('C:\\');
+    });
+    it('skips rules without applyTo (those belong in the repo-wide file)', () => {
+        const files = generateCopilotInstructionFiles([{ name: 'Repo Wide', body: 'general guidance' }], TIMESTAMP);
+        expect(files).toHaveLength(0);
+    });
+    it('de-dupes basenames deterministically so two rules never clobber one file', () => {
+        const files = generateCopilotInstructionFiles([
+            { name: 'Boundaries', applyTo: 'a/**', body: 'one' },
+            { name: 'boundaries', applyTo: 'b/**', body: 'two' },
+        ], TIMESTAMP);
+        expect(files.map((f) => f.relativePath)).toEqual([
+            '.github/instructions/boundaries.instructions.md',
+            '.github/instructions/boundaries-2.instructions.md',
+        ]);
+    });
+});
+//# sourceMappingURL=adapters.test.js.map