@stravica-ai/digital-operator-pa 0.1.39 → 0.1.41

package/dist/engineering-pa-scaffold/src/generator.mjs

@@ -7,7 +7,8 @@
 // kind: 'dir' (mkdir -p) | 'file' (write file with contents) | 'json'
 // (stringify + write).
 
-import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -18,6 +19,14 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Path to the CLAUDE.md template (relative to this module). */
 export const CLAUDE_MD_TEMPLATE_PATH = resolve(__dirname, '..', 'templates', 'CLAUDE.md.template');
 
+/** Path to the root-CLAUDE.md pointer template (relative to this module). */
+export const ROOT_CLAUDE_MD_TEMPLATE_PATH = resolve(
+  __dirname,
+  '..',
+  'templates',
+  'root-CLAUDE.md.template',
+);
+
 /** Path to the operator README template (relative to this module). */
 export const OPERATOR_README_TEMPLATE_PATH = resolve(
   __dirname,
@@ -26,6 +35,65 @@ export const OPERATOR_README_TEMPLATE_PATH = resolve(
   'operator-README.md.template',
 );
 
+/**
+ * Path to the `/research` slash-command doc, resolved out of the bundled
+ * engineering-pa-core package. Two candidates so this works both from the
+ * source monorepo (`packages/scaffold/src/generator.mjs` → `packages/core/…`)
+ * and from the packed tarball (`dist/engineering-pa-scaffold/src/generator.mjs`
+ * → `dist/engineering-pa-core/…`). The scaffold reads the file at plan time
+ * so the copy the colleague gets never drifts from the packaged canonical.
+ */
+const RESEARCH_COMMAND_CANDIDATES = [
+  resolve(__dirname, '..', '..', 'engineering-pa-core', 'docs', 'commands', 'research.md'),
+  resolve(__dirname, '..', '..', 'core', 'docs', 'commands', 'research.md'),
+];
+
+export const RESEARCH_COMMAND_TEMPLATE_PATH =
+  RESEARCH_COMMAND_CANDIDATES.find((p) => existsSync(p)) ?? RESEARCH_COMMAND_CANDIDATES[0];
+
+/**
+ * Path to the bundled `workspace-extensions.md` PA-facing knowledge doc,
+ * resolved out of the packaged core. Two candidates so this works in both
+ * the source monorepo (`packages/scaffold/src/generator.mjs` -> `packages/core/...`)
+ * and the packed tarball (`dist/engineering-pa-scaffold/src/generator.mjs`
+ * -> `dist/engineering-pa-core/...`). The scaffold seeds the doc into
+ * `operator/knowledge/platform-tooling/workspace-extensions.md` so that
+ * `pa knowledge search "workspace extension"` reaches it in a fresh
+ * scaffolded solo instance (the retrieval graph scans `operator/knowledge/`
+ * and `core/knowledge/` under the repo root, and a solo scaffold ships
+ * neither of those trees populated by default).
+ */
+const WORKSPACE_EXTENSIONS_KNOWLEDGE_CANDIDATES = [
+  resolve(__dirname, '..', '..', 'engineering-pa-core', 'knowledge', 'platform-tooling', 'workspace-extensions.md'),
+  resolve(__dirname, '..', '..', 'core', 'knowledge', 'platform-tooling', 'workspace-extensions.md'),
+];
+
+export const WORKSPACE_EXTENSIONS_KNOWLEDGE_PATH =
+  WORKSPACE_EXTENSIONS_KNOWLEDGE_CANDIDATES.find((p) => existsSync(p))
+  ?? WORKSPACE_EXTENSIONS_KNOWLEDGE_CANDIDATES[0];
+
+/**
+ * Path to the bundled `rcf-lite/` link-led knowledge bucket, resolved out
+ * of the packaged engineering role pack. Two candidates so this works in
+ * both the source monorepo (`packages/scaffold/src/generator.mjs` ->
+ * `packages/types/engineering/knowledge/rcf-lite/`) and the packed tarball
+ * (`dist/engineering-pa-scaffold/src/generator.mjs` ->
+ * `dist/engineering-pa-types-engineering/knowledge/rcf-lite/`). The
+ * scaffold seeds every `.md` file in this directory into
+ * `operator/knowledge/rcf-lite/` so `pa knowledge search "rcf-lite"`
+ * reaches the bucket in a fresh scaffolded solo instance (the retrieval
+ * graph scans `operator/knowledge/` and `core/knowledge/` under the repo
+ * root; a bundled-only copy would be invisible to the search verb).
+ */
+const RCF_LITE_KNOWLEDGE_DIR_CANDIDATES = [
+  resolve(__dirname, '..', '..', 'engineering-pa-types-engineering', 'knowledge', 'rcf-lite'),
+  resolve(__dirname, '..', '..', 'types', 'engineering', 'knowledge', 'rcf-lite'),
+];
+
+export const RCF_LITE_KNOWLEDGE_DIR_PATH =
+  RCF_LITE_KNOWLEDGE_DIR_CANDIDATES.find((p) => existsSync(p))
+  ?? RCF_LITE_KNOWLEDGE_DIR_CANDIDATES[0];
+
 /**
  * The base set of knowledge domains seeded into every fresh PA instance.
  * Per the methodology doc: engineering, ops, agent-ops, knowledge-meta,
@@ -78,6 +146,19 @@ export function renderClaudeMd(template, config) {
     .replaceAll('{COMMUNICATION_STYLE}', config.communicationStyle);
 }
 
+/**
+ * Render the root-CLAUDE.md pointer with the config. The root file is a
+ * short quick-reference that points at the full agent CLAUDE.md — the
+ * split mirrors the established estate convention (root pointer +
+ * canonical agent file) so the two files never drift as byte-identical
+ * duplicates.
+ */
+export function renderRootClaudeMd(template, config) {
+  return template
+    .replaceAll('{PA_NAME}', config.paName)
+    .replaceAll('{OPERATOR_NAME}', config.operatorName);
+}
+
 /**
  * Render the operator-repo README template. Uses the same token set as
  * CLAUDE.md.template for consistency.
@@ -205,7 +286,13 @@ export function buildExtensionsManifest(config) {
   return {
     version: '1.0',
     generatedAt: config.generatedAt,
-    extensions: [],
+    extensions: [
+      {
+        id: 'atlassian',
+        enabled: true,
+        note: 'Common-use Atlassian CLIs (jira, confluence, confluence-fetch). Configure with: secrets set JIRA_DOMAIN <site>; secrets set JIRA_EMAIL <email>; secrets set JIRA_API_TOKEN <token>.',
+      },
+    ],
     note: 'Extensions land in Phase 2. This manifest is the registration surface for promoted core extensions and operator-private extensions.',
   };
 }
@@ -302,6 +389,69 @@ export function buildGitkeep() {
   return '';
 }
 
+/**
+ * Build the .claude/settings.json contents.
+ *
+ * Two things:
+ *   1. `permissions.deny` for the built-in `deep-research` skill and
+ *      workflow. The core operating model (Bucket 4) directs the PA to
+ *      the `/research` verb, which persists a session and promotes
+ *      durable answers back into the knowledge library. The built-in
+ *      `deep-research` skill produces no such trail and would silently
+ *      short-circuit the discipline; deny is the correct default.
+ *
+ *   2. `hooks.PreToolUse` wiring `pa-coordinator-hook` for the matcher
+ *      the coordinator-hook doc gives. The hook is a no-op unless the
+ *      operator sets `PA_COORDINATOR_MODE=1` in their shell, so the
+ *      scaffold ships the wiring inert. A per-repo overlay slot is
+ *      scaffolded alongside as `.claude/coordinator-overlay.json`.
+ *
+ * SessionStart hooks (boot-context style injection) are deliberately
+ * NOT scaffolded — the boot-context tool lives in the HQ estate, not
+ * the published package. Scaffolding a hook that names a binary the
+ * colleague does not have would fire on every session boot with a
+ * non-blocking error. Documented in docs/onboarding-solo.md under
+ * "what is not included in solo mode".
+ */
+export function buildClaudeSettingsJson() {
+  return {
+    permissions: {
+      deny: ['Skill(skill:deep-research)', 'Workflow(name:deep-research)'],
+    },
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: '^(Bash|Read|Write|Edit|NotebookEdit|Grep|Glob|WebFetch|WebSearch)$',
+          hooks: [
+            {
+              type: 'command',
+              command: 'pa-coordinator-hook',
+            },
+          ],
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Build the .claude/coordinator-overlay.json starter. The overlay is a
+ * per-repo extension slot for `pa-coordinator-hook` — see the doc at
+ * packages/cli/docs/coordinator-hook.md for the merge contract. Only
+ * `tier2.<Bash|Read|Write>.allowPatterns` / `.allowPathPatterns` may be
+ * extended; the file ships empty so the presence of the overlay is
+ * documentation on its own without widening the default policy.
+ */
+export function buildCoordinatorOverlayJson() {
+  return {
+    tier2: {
+      Bash: { allowPatterns: [] },
+      Read: { allowPathPatterns: [] },
+      Write: { allowPathPatterns: [] },
+    },
+  };
+}
+
 /**
  * Compose the full plan. Returns an ordered list of `{ kind, path, contents }`
  * relative to `config.targetDir`. The runner resolves the paths and writes
@@ -309,8 +459,37 @@ export function buildGitkeep() {
  */
 export async function buildPlan(config) {
   const claudeTemplate = await readFile(CLAUDE_MD_TEMPLATE_PATH, 'utf8');
+  const rootClaudeTemplate = await readFile(ROOT_CLAUDE_MD_TEMPLATE_PATH, 'utf8');
   const operatorReadmeTemplate = await readFile(OPERATOR_README_TEMPLATE_PATH, 'utf8');
-  return buildPlanFromTemplates(config, { claudeTemplate, operatorReadmeTemplate });
+  const researchCommand = await readFile(RESEARCH_COMMAND_TEMPLATE_PATH, 'utf8');
+  const workspaceExtensionsKnowledge = await readFile(WORKSPACE_EXTENSIONS_KNOWLEDGE_PATH, 'utf8');
+  const rcfLiteKnowledge = await readRcfLiteKnowledge(RCF_LITE_KNOWLEDGE_DIR_PATH);
+  return buildPlanFromTemplates(config, {
+    claudeTemplate,
+    rootClaudeTemplate,
+    operatorReadmeTemplate,
+    researchCommand,
+    workspaceExtensionsKnowledge,
+    rcfLiteKnowledge,
+  });
+}
+
+/**
+ * Read every `.md` file in the packaged rcf-lite knowledge directory and
+ * return a `{ filename: contents }` map for seeding into the scaffolded
+ * `operator/knowledge/rcf-lite/` tree. Returns `null` when the directory
+ * is absent so the pure-plan seam degrades to "skip the seed" rather than
+ * throwing, matching the workspace-extensions behaviour.
+ */
+export async function readRcfLiteKnowledge(dirPath) {
+  if (!existsSync(dirPath)) return null;
+  const entries = await readdir(dirPath);
+  const files = entries.filter((n) => n.endsWith('.md')).sort();
+  const out = {};
+  for (const filename of files) {
+    out[filename] = await readFile(join(dirPath, filename), 'utf8');
+  }
+  return out;
 }
 
 /**
@@ -321,6 +500,13 @@ export async function buildPlan(config) {
 export function buildPlanFromTemplates(config, templates) {
   const { paName } = config;
   const claudeMd = renderClaudeMd(templates.claudeTemplate, config);
+  // Root-CLAUDE.md is a short pointer to the full agent file. Falling
+  // back to the agent file when the pointer template is absent keeps
+  // pure-plan tests that only pass `claudeTemplate` working, while the
+  // real buildPlan() path always supplies both.
+  const rootClaudeMd = templates.rootClaudeTemplate
+    ? renderRootClaudeMd(templates.rootClaudeTemplate, config)
+    : claudeMd;
   const readmeMd = renderOperatorReadme(templates.operatorReadmeTemplate, config);
   const pkg = buildOperatorPackageJson(config);
   const gitignore = buildGitignore();
@@ -348,20 +534,70 @@ export function buildPlanFromTemplates(config, templates) {
     'projects',
     'schedules',
     '.vault',
+    '.claude',
+    '.claude/commands',
   ];
 
   const plan = [];
   for (const d of dirs) plan.push({ kind: 'dir', path: d });
 
-  plan.push({ kind: 'file', path: 'CLAUDE.md', contents: claudeMd });
+  plan.push({ kind: 'file', path: 'CLAUDE.md', contents: rootClaudeMd });
   plan.push({ kind: 'file', path: 'README.md', contents: readmeMd });
   plan.push({ kind: 'json', path: 'package.json', contents: pkg });
   plan.push({ kind: 'file', path: '.gitignore', contents: gitignore });
   plan.push({ kind: 'file', path: '.nvmrc', contents: '24\n' });
 
+  plan.push({ kind: 'json', path: '.claude/settings.json', contents: buildClaudeSettingsJson() });
+  // /research slash command: rendered from the packaged core doc so the
+  // command a colleague gets is exactly what the platform ships. The scaffold
+  // never re-authors it, and there is no template to drift.
+  if (templates.researchCommand) {
+    plan.push({
+      kind: 'file',
+      path: '.claude/commands/research.md',
+      contents: templates.researchCommand,
+    });
+  }
+  plan.push({
+    kind: 'json',
+    path: '.claude/coordinator-overlay.json',
+    contents: buildCoordinatorOverlayJson(),
+  });
+
   plan.push({ kind: 'file', path: 'operator/profile/profile.md', contents: profile });
   plan.push({ kind: 'json', path: 'operator/knowledge/domains.json', contents: domains });
   plan.push({ kind: 'json', path: 'operator/knowledge/index.json', contents: knowledgeIndex });
+  // Seed the PA-facing workspace-extensions knowledge doc into the operator
+  // tree so `pa knowledge search "workspace extension"` reaches it. The
+  // retrieval graph scans `operator/knowledge/` and `core/knowledge/` under
+  // the repo root; a solo scaffold ships neither of those trees populated
+  // by default, so a bundled-only copy would be invisible to the search
+  // verb. Kept in lockstep with the packaged canonical via the plan-time
+  // read at WORKSPACE_EXTENSIONS_KNOWLEDGE_PATH.
+  if (templates.workspaceExtensionsKnowledge) {
+    plan.push({
+      kind: 'file',
+      path: 'operator/knowledge/platform-tooling/workspace-extensions.md',
+      contents: templates.workspaceExtensionsKnowledge,
+    });
+  }
+  // Seed the link-led rcf-lite knowledge bucket into the operator tree so
+  // `pa knowledge search "rcf-lite"` reaches every file. Same rationale as
+  // the workspace-extensions doc above: the retrieval graph scans
+  // `operator/knowledge/` and `core/knowledge/` under the repo root, so a
+  // bundled-only copy is invisible to the search verb. `templates.rcfLiteKnowledge`
+  // is a `{ filename: contents }` map read by `readRcfLiteKnowledge` from
+  // the packaged types/engineering pack at plan time; pure-plan callers
+  // omit the field to skip the seed (backwards compatible).
+  if (templates.rcfLiteKnowledge) {
+    for (const [filename, contents] of Object.entries(templates.rcfLiteKnowledge)) {
+      plan.push({
+        kind: 'file',
+        path: `operator/knowledge/rcf-lite/${filename}`,
+        contents,
+      });
+    }
+  }
   plan.push({ kind: 'json', path: 'operator/config/preferences.json', contents: buildPreferencesJson(config) });
   plan.push({ kind: 'json', path: 'operator/extensions/manifest.json', contents: manifest });
 

package/dist/engineering-pa-scaffold/templates/CLAUDE.md.template

@@ -10,7 +10,7 @@ You are a colleague, not a servant. You have opinions and you voice them -- with
 
 Your long-term goal is to learn {OPERATOR_NAME}'s judgement so thoroughly that you can operate autonomously on their behalf -- making decisions, managing tasks, running delegated work -- without needing to ask. Every interaction is training data. The measure of progress: how often can you act without escalating? Every question you have to ask that you could have answered is a gap.
 
-**PA operating mode — dispatch-first. This is the defining posture; re-read it every boot.** Your main thread exists for three things only: (1) orchestrating work, (2) keeping the work-trail current (work items, projects, spawn-log, journal, staging), and (3) interacting with {OPERATOR_NAME}. **ALL substantive work goes into a dispatch** — a subagent with a full 8-section brief. Research, writing, code, analysis, multi-file reads, anything that produces a work product: dispatched, not done inline. You lead the team by delegating, not by doing. Keeping the main thread clean is what keeps you available to {OPERATOR_NAME} and stops you burning context on work you could have handed off. The narrow inline exceptions (a one-line edit, a single file read, a status answer) are enumerated in Bucket 3 — treat them as the exception, never the reflex. When unsure: dispatch.
+**PA operating mode. Dispatch-first. This is the defining posture; re-read it every boot.** Your main thread exists for three things only: (1) orchestrating work, (2) keeping the work-trail current (work items, projects, spawn-log, journal, staging), and (3) interacting with {OPERATOR_NAME}. **ALL substantive work goes into a dispatch**: a subagent with a full 8-section brief. Research, writing, code, analysis, multi-file reads, anything that produces a work product: dispatched, not done inline. You lead the team by delegating, not by doing. Keeping the main thread clean is what keeps you available to {OPERATOR_NAME} and stops you burning context on work you could have handed off. The narrow inline exceptions (a one-line edit, a single file read, a status answer) are enumerated in Bucket 3. Treat them as the exception, never the reflex. When unsure: dispatch.
 
 **Autonomy envelope.** Per-task-type approval state lives at `agents/{PA_NAME}/autonomy-envelope.md`. Three states: `fullyApproved` (act, don't ask), `checkBeforeCommitting` (draft, get sign-off before durable action), `needsFullSupervision` (do not act; escalate every step). {OPERATOR_NAME} promotes or demotes at any time via `pa autonomy set`. The envelope is the durable record; your judgement calibrates day-to-day, but the envelope is what you check when the reflex is unclear. See `@stravica-ai/engineering-pa-core/docs/autonomy-envelope-tracker.md`.
 
@@ -97,7 +97,7 @@ Right information at the right time. Repo is truth; memory is cache.
 
 Ship correct, safe, reversible changes. Never destroy {OPERATOR_NAME}'s work.
 
-1. **Match the engineering role to the shape of work.** Base role ladder: `tool-developer` (shared internal CLI) → `web-developer` (content-led marketing site) → `product-engineer` (shippable single-app software) → `rcf-engineer` (enterprise product with full RCF traceability). Operator-side specialisations (site-cloner, seo-*, infographic-designer, etc.) layer above. Wrong tier ships wrong.
+1. **Match the engineering role to the shape of work.** Base role ladder: `tool-developer` (shared internal CLI) → `web-developer` (content-led marketing site) → `product-engineer` (prototypes, local apps and utilities) → `rcf-lite-engineer` (shippable greenfield apps up to small commercial SaaS on the rcf-lite spine; not brownfield/enterprise) → `rcf-engineer` (enterprise product with full RCF traceability). Operator-side specialisations (site-cloner, seo-*, infographic-designer, etc.) layer above. Wrong tier ships wrong. The `rcf-lite-engineer` role definition and its link-led knowledge bucket live at `operator/knowledge/rcf-lite/` (seeded from the packaged engineering role pack); rcf-lite installs per project via `npm install rcf-lite`.
 2. **Verify runtime behaviour, not just type-check + tests.** Tests verify code correctness, not feature correctness. If you can't test the UI, say so explicitly.
 3. **Blast-radius awareness.** Local reversible = free. Shared / hard-to-reverse / visible to others = confirm first. Match action scope to what was requested.
 4. **Investigate root causes.** Don't bypass safety checks (`--no-verify`) as a shortcut.
@@ -107,7 +107,7 @@ Ship correct, safe, reversible changes. Never destroy {OPERATOR_NAME}'s work.
 8. **Investigate unexpected state before overwriting.** Unfamiliar files / branches / config may represent {OPERATOR_NAME}'s in-progress work. `git status` before any command that could discard uncommitted changes.
 9. **When staging or committing, review what's included.** Never commit files that likely contain secrets. Suspicious filenames get their contents checked before push.
 
-**Deeper reference:** `operator/knowledge/engineering-discipline/` -- role-ladder + selection heuristics, git safety protocol, worktree-isolation patterns, verify skill catalogue, blast-radius examples, secret-scanning heuristics.
+**Deeper reference:** `operator/knowledge/engineering-discipline/` -- role-ladder + selection heuristics, git safety protocol, worktree-isolation patterns, verify skill catalogue, blast-radius examples, secret-scanning heuristics. **rcf-lite:** `operator/knowledge/rcf-lite/` -- link-led bucket into `https://stravica.ai/docs/rcf/` (start here / wire your agent / how it works / driving / for agents / reference), plus the one local `create-a-small-app.md` command sequence.
 
 <!-- OPERATOR: list operator-side specialised engineering roles here (the role LIST beyond the base ladder), plus operator-specific engineering conventions (per-project git safety rules, CI-integration patterns, downstream-repo policies). -->
 
@@ -129,7 +129,7 @@ Content that lands in {OPERATOR_NAME}'s voice, not generic AI-speak. Route throu
 
 Use the estate's own tooling first. Consistent, dogfooded, learnable.
 
-1. **Always use local tooling before reaching for others.** Discover the current surface every session -- don't rely on memory. Sources: `pnpm exec pa --help`, `pnpm exec desk --help`, `ls operator/extensions/tools/`. External tools only when nothing local fits.
+1. **Always use local tooling before reaching for others.** Discover the current surface every session -- don't rely on memory. Sources: `pnpm exec pa --help`, `pnpm exec desk --help`, `pnpm exec jira --help`, `pnpm exec confluence --help`, `pnpm exec confluence-fetch --help`, `ls operator/extensions/tools/`. External tools only when nothing local fits.
 2. **Environmental awareness.** `pa environment` runs on session boot -- lightweight core CLI that populates `.session/environment.json` in <2s (OS, tools, network reachability, workspace state, working directory). Default `pa environment` reads the cache; `pa environment refresh` rebuilds. Deeper diagnostics via `pa environment extended` (operator overlay) run on demand only. Factor environment into decisions -- dispatch target, tool availability, network access.
 3. **Platform CLIs invoked via `pnpm exec`** -- platform ships as `@stravica-ai/digital-operator-pa` npm package.
 4. **`desk` CLI is read-only.** Overview, today, work, projects. Never edit through desk.
@@ -137,9 +137,9 @@ Use the estate's own tooling first. Consistent, dogfooded, learnable.
 6. **Scheduling:** `schedules/{id}.json`. Default target host is an operator-configured field -- name it in your operator overlay.
 7. **MCP servers available on demand:** discover via `--help` on the tool surface. Use when the task fits; don't force.
 8. **Working directory ≠ project root.** cwd is `agents/{PA_NAME}/`; derive project root via `.session/environment.json:workingDirectory.projectRoot` or a `*_ROOT` env var. Never hard-code paths.
-9. **Proactive tool proposal.** When a task pattern repeats or is complex enough that manual execution is error-prone, propose a tool to {OPERATOR_NAME}. On approval, dispatch tool-developer at the next convenient point. Don't wait for {OPERATOR_NAME} to suggest -- building a decent library of helpful tools is estate improvement work you own.
+9. **Proactive tool proposal.** When a task pattern repeats or is complex enough that manual execution is error-prone, propose a tool to {OPERATOR_NAME}. On approval, dispatch tool-developer at the next convenient point. Don't wait for {OPERATOR_NAME} to suggest -- building a decent library of helpful tools is estate improvement work you own. **Workspace pages count as a tool for this rule.** When {OPERATOR_NAME}'s habits fit the triggers in `operator/knowledge/platform-tooling/workspace-extensions.md` (repeated manual view, explicit ask for a dashboard, an installed tool with a natural page), propose a workspace extension and, on approval, invoke `pa-init workspace-extension <name>` for the skeleton before dispatching `tool-developer` for the real content.
 
-**Deeper reference:** `operator/knowledge/platform-tooling/` -- pa/desk/pnpm-exec/workspace reference, tool-discovery discipline, environment-awareness protocol (`pa environment` core + `extended` overlay), scheduling API, MCP server catalogue, proactive-tool-proposal pattern.
+**Deeper reference:** `operator/knowledge/platform-tooling/` -- pa/desk/pnpm-exec/workspace reference, tool-discovery discipline, environment-awareness protocol (`pa environment` core + `extended` overlay), scheduling API, MCP server catalogue, proactive-tool-proposal pattern, workspace-extension prompting (`workspace-extensions.md`).
 
 <!-- OPERATOR: list your `operator/extensions/tools/` (custom operator tools you have built), your workspace port if not 4200, your scheduling default host, and MCP servers you rely on. -->
 
@@ -193,6 +193,6 @@ Stage observations, update journal, update work items, update spawn-log outcomes
 
 All paths are relative to the operator repo root. Resolve via `.session/environment.json:workingDirectory.projectRoot` or a `*_ROOT` env var, never hard-code absolutes.
 
-Symbolic `@stravica-ai/engineering-pa-core/<subpath>` references resolve on disk to `node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-core/<subpath>` — the internal packages ship bundled inside the wrapper package, not under their own names in `node_modules`.
+Symbolic `@stravica-ai/engineering-pa-core/<subpath>` references resolve on disk to `node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-core/<subpath>`. The internal packages ship bundled inside the wrapper package, not under their own names in `node_modules`.
 
 <!-- OPERATOR: add any operator-specific paths that are frequently referenced (a vault path, a scratchpad convention, an integration credentials store). -->

package/dist/engineering-pa-scaffold/templates/operator-README.md.template

@@ -1,8 +1,8 @@
-# {PA_NAME} — operator repo
+# {PA_NAME}: operator repo
 
 Personal-assistant instance for {OPERATOR_NAME}, scaffolded with `pa-init`.
 
-This repo holds **only operator content** — your profile, knowledge, work items,
+This repo holds **only operator content**: your profile, knowledge, work items,
 projects, agent run state, schedules, and secrets. The PA platform code is
 supplied by the `@stravica-ai/digital-operator-pa` npm package; you never edit it in
 place.
@@ -17,7 +17,7 @@ place.
 │   ├── profile/              # operator profile (distilled over time)
 │   ├── knowledge/            # domain-organised knowledge tree
 │   └── extensions/           # operator-private extensions (Phase 2+)
-├── agents/{PA_NAME}/         # PA run folder — journal, staging, spawn-log
+├── agents/{PA_NAME}/         # PA run folder: journal, staging, spawn-log
 ├── work/                     # work items (one JSON per item)
 ├── projects/                 # projects (one folder per project)
 ├── schedules/                # scheduled-task definitions
@@ -28,7 +28,7 @@ place.
 
 ```bash
 pnpm install
-pnpm status            # alias for `pa status` — boot-time sanity check
+pnpm status            # alias for `pa status`, a boot-time sanity check
 ```
 
 Then launch your PA via Claude Code in this repo; it reads `CLAUDE.md`

package/dist/engineering-pa-scaffold/templates/root-CLAUDE.md.template

@@ -0,0 +1,13 @@
+# {PA_NAME}
+
+Personal assistant platform instance for {OPERATOR_NAME}. See `agents/{PA_NAME}/CLAUDE.md` for the full operating instructions. That file is the source of truth for how {PA_NAME} works and is the one Claude Code loads when you start a session from the agent directory.
+
+## Quick reference
+
+- Work items: `work/w-YYYY-MM-DD-NNN.json`
+- Projects: `projects/{id}/project.json`
+- Operator content: `operator/`
+- Agent run folder: `agents/{PA_NAME}/`
+- Platform package: installed as an npm dependency (`@stravica-ai/digital-operator-pa`); invoke tooling via `pnpm exec <bin>` (`pa`, `desk`, `secrets`, `distill`, etc.)
+- Workspace: `pnpm exec pa workspace start` then http://localhost:4200
+- Onboarding guide: `node_modules/@stravica-ai/digital-operator-pa/docs/onboarding-solo.md`

package/dist/engineering-pa-types-engineering/index.mjs

@@ -1,9 +1,17 @@
-// @stravica-ai/engineering-pa-types-engineering — engineering-PA role pack.
+// @stravica-ai/engineering-pa-types-engineering - engineering-PA role pack.
 //
-// Currently ships the product-engineer role and the `product-build`
-// slash-command doc. Additional engineering-PA roles (project-lead, generic
-// system-architect, generic web-developer) are planned for Phase 2.
+// Ships:
+//   - product-engineer: prototypes, local apps, utilities on the estate's
+//     opinionated Docker + CI + node:test spine.
+//   - rcf-lite-engineer: shippable greenfield apps up to small commercial
+//     SaaS on the rcf-lite spec-and-build spine (see the knowledge/rcf-lite
+//     bucket for its link-led reference).
+//   - The `product-build` slash-command doc under docs/.
+//
+// Role sources live under roles/<role>/definition.md. A role.json is
+// optional; both roles here ship definition.md only. The pack is copied
+// verbatim into dist/engineering-pa-types-engineering/ by the packager.
 
 export const name = './';
-export const version = '0.1.1';
-export const roles = ['product-engineer'];
+export const version = '0.2.0';
+export const roles = ['product-engineer', 'rcf-lite-engineer'];

package/dist/engineering-pa-types-engineering/knowledge/rcf-lite/create-a-small-app.md

@@ -0,0 +1,81 @@
+# Create a small app or service with rcf-lite from a fresh PA
+
+The one local how-to allowed in this bucket. Every command below has been checked against `npx rcf --help` on the published rcf-lite (see `Verified against` at the bottom).
+
+Prerequisites: Node.js 24 or newer; git; a Claude Code (or equivalent) harness set up in the shell.
+
+## The numbered sequence
+
+1. Make and enter the project directory.
+
+   ```sh
+   mkdir my-app && cd my-app
+   git init -q
+   ```
+
+2. Install `rcf-lite` per project (not global, so different apps can pin different versions).
+
+   ```sh
+   npm init -y
+   npm install rcf-lite
+   ```
+
+3. Scaffold the `rcf/` tree and wire the harness. `rcf init` writes the tree, registers the MCP server in `.mcp.json`, and drops the agent-instructions fragment into `CLAUDE.md` and `AGENTS.md`.
+
+   ```sh
+   npx rcf init --project-name my-app --non-interactive
+   ```
+
+   Interactive form (drop `--non-interactive`): the CLI prompts only for the project name.
+
+4. Confirm the wiring is healthy. `rcf doctor` diagnoses and repairs init-hygiene drift; run it any time the harness looks off.
+
+   ```sh
+   npx rcf doctor
+   ```
+
+5. Pick a blueprint from the shelf (the packaged shelf that ships with rcf-lite). Two examples the shelf carries by name:
+
+   ```sh
+   npx rcf define blueprint add deploy-cloudflare-workers
+   npx rcf define blueprint add application-spa
+   ```
+
+   List everything that has been applied so far, grouped by category:
+
+   ```sh
+   npx rcf define blueprint list
+   ```
+
+6. Enter the build loop.
+
+   ```sh
+   npx rcf build queue                # what is scheduled next
+   npx rcf build bundle --next        # spec bundle for the next FBS
+   # then implement the FBS in code, keeping the suite green
+   npx rcf build finalise <fbs-id>    # ship gate for one FBS
+   ```
+
+7. Run the audit surface as the tree grows.
+
+   ```sh
+   npx rcf audit view                 # live HTML tree render (long-running)
+   npx rcf audit coverage             # structural coverage over the REQ chain
+   npx rcf audit trace <id>           # walk the graph forward, back, or both
+   ```
+
+8. When the candidate is ready, hand it back for the independent verifier. The RCF Lite Engineer never self-certifies as ship-ready; the orchestrator dispatches the verify session against the deployed runtime.
+
+   ```sh
+   npx rcf verify run                 # run the adversarial ship-gate verifier
+   ```
+
+## Verified against
+
+- `rcf-lite@0.27.0` (`npm view rcf-lite version` at 2026-09-16). Commands above match the top-level groups (`define`, `build`, `verify`, `audit`) and the verbs (`init`, `doctor`, `define blueprint {add,list,remove}`, `build {queue,bundle,mark,finalise}`, `verify run`, `audit {view,coverage,trace}`) shown by `npx rcf --help` and `npx rcf help define blueprint`.
+- Blueprint slugs `deploy-cloudflare-workers` and `application-spa` are the shelf resolvers documented by `rcf define blueprint add <source>` help (bare kebab slugs resolve to the packaged shelf).
+
+## See also
+
+- Full CLI reference on the docs site: [https://stravica.ai/docs/rcf/reference/cli/](https://stravica.ai/docs/rcf/reference/cli/)
+- Build-cycle playbook for the agent driving the loop: [https://stravica.ai/docs/rcf/for-agents/build-cycle-playbook/](https://stravica.ai/docs/rcf/for-agents/build-cycle-playbook/)

package/dist/engineering-pa-types-engineering/knowledge/rcf-lite/for-agents.md

@@ -0,0 +1,25 @@
+# rcf-lite for agents
+
+The RCF Lite Engineer role definition (`../../roles/rcf-lite-engineer/definition.md`) is the operating spine. This doc is the pointer set into the agent-facing pages on the Stravica docs site; the docs are the current source of truth for method-level detail.
+
+## Playbooks
+
+- **Build cycle playbook (the five-stage loop the RCF Lite Engineer runs):** [https://stravica.ai/docs/rcf/for-agents/build-cycle-playbook/](https://stravica.ai/docs/rcf/for-agents/build-cycle-playbook/)
+- **Elicitation playbook (how to draw the PRD/REQ/US/AC content out of the operator):** [https://stravica.ai/docs/rcf/for-agents/elicitation-playbook/](https://stravica.ai/docs/rcf/for-agents/elicitation-playbook/)
+- **Document model (what each RCF document is for and how it links):** [https://stravica.ai/docs/rcf/for-agents/document-model/](https://stravica.ai/docs/rcf/for-agents/document-model/)
+- **Harness block (the fragment `rcf init` writes into `CLAUDE.md`/`AGENTS.md`):** [https://stravica.ai/docs/rcf/for-agents/harness-block/](https://stravica.ai/docs/rcf/for-agents/harness-block/)
+- **MCP surface (the tool surface the agent gets when the harness is wired):** [https://stravica.ai/docs/rcf/for-agents/mcp-surface/](https://stravica.ai/docs/rcf/for-agents/mcp-surface/)
+- **Persona programme (the failure classes that shaped the role's disciplines):** [https://stravica.ai/docs/rcf/for-agents/persona-programme/](https://stravica.ai/docs/rcf/for-agents/persona-programme/)
+
+## Deploy-target-first
+
+The role's first discipline is naming the deploy target before locking a stack. See:
+
+- **Cloudflare-first projects (the reference edge stack for rcf-lite):** [https://stravica.ai/docs/rcf/for-agents/cloudflare-first-projects/](https://stravica.ai/docs/rcf/for-agents/cloudflare-first-projects/)
+
+## How the pieces fit
+
+- **The chain and the referee (what the tooling guarantees about the tree):** [https://stravica.ai/docs/rcf/how-it-works/the-chain/](https://stravica.ai/docs/rcf/how-it-works/the-chain/), [https://stravica.ai/docs/rcf/how-it-works/what-the-referee-guarantees/](https://stravica.ai/docs/rcf/how-it-works/what-the-referee-guarantees/)
+- **The five-stage build cycle (define, design, build, test, review):** [https://stravica.ai/docs/rcf/how-it-works/the-five-stage-build-cycle/](https://stravica.ai/docs/rcf/how-it-works/the-five-stage-build-cycle/)
+- **Coverage, trace, impact (the tree audit surface):** [https://stravica.ai/docs/rcf/how-it-works/coverage-trace-impact/](https://stravica.ai/docs/rcf/how-it-works/coverage-trace-impact/)
+- **Blueprints as composition units:** [https://stravica.ai/docs/rcf/how-it-works/blueprints/](https://stravica.ai/docs/rcf/how-it-works/blueprints/)

package/dist/engineering-pa-types-engineering/knowledge/rcf-lite/index.md

@@ -0,0 +1,34 @@
+# rcf-lite
+
+rcf-lite is a lightweight spec-and-build spine for greenfield software. It gives an agent a Requirements Confidence Framework tree (PRD -> REQ -> US -> AC -> FBS) plus a green test suite that gates each build, without the ceremony of the full enterprise RCF chain. It is the tier the `rcf-lite-engineer` role builds on.
+
+The role is chosen when the deliverable is a real shippable application (weekend utility up to small commercial SaaS) that needs a proper requirements-confidence spine, not a prototype or an internal script. If the task is a static site, a local utility, or a full enterprise product, pick a different role from the ladder.
+
+## Where to read next
+
+- **Start here (product overview + status + release notes):** [https://stravica.ai/docs/rcf/](https://stravica.ai/docs/rcf/), [https://stravica.ai/docs/rcf/status/](https://stravica.ai/docs/rcf/status/), [https://stravica.ai/docs/rcf/changelog/](https://stravica.ai/docs/rcf/changelog/)
+- **How it works (the chain, the five-stage build cycle, blueprints, coverage/trace/impact, what the referee guarantees):** [https://stravica.ai/docs/rcf/how-it-works/](https://stravica.ai/docs/rcf/how-it-works/)
+- **Driving one as an operator (steering, reviewing the tree, handing over, when it goes wrong):** [https://stravica.ai/docs/rcf/driving/](https://stravica.ai/docs/rcf/driving/)
+- **Guides (add rcf to an existing repo, close the loop without a deploy, kick the tyres by hand, wiring alternatives, the tree viewer):** [https://stravica.ai/docs/rcf/guides/](https://stravica.ai/docs/rcf/guides/)
+- **For agents (the playbook the RCF Lite Engineer works from):** see the sibling doc `for-agents.md`.
+- **Reference (CLI, document types, exit codes, blueprints shelf):** see the sibling doc `reference.md`.
+- **Wiring an agent into a project (harness, MCP, `rcf init`):** see the sibling doc `wire-your-agent.md`.
+
+The Stravica docs site is the current source of truth; the docs in this bucket are framing and pointers so the local knowledge stays in sync as the docs move.
+
+## When to reach for it
+
+- Greenfield: no existing codebase to retrofit into.
+- Small-to-mid ambition: from a weekend utility up to a small commercial SaaS. Anything multi-tenant, regulated, or contractually-audited is `rcf-engineer` territory, not this tier.
+- The operator wants a real requirements spine and a green-gated build, not a code-first prototype.
+- The output needs to be a candidate the operator can point an independent verifier at before shipping.
+
+## When not to
+
+- A brownfield retrofit or an enterprise/full-RCF build. Escalate to the tier above.
+- A single-file utility or a throwaway prototype. Escalate to `product-engineer` below.
+- A static site or content-led marketing page. Escalate to `web-developer` below.
+
+## Local how-to
+
+The one local how-to allowed in this bucket is `create-a-small-app.md`. Everything else links out to the docs site.

package/dist/engineering-pa-types-engineering/knowledge/rcf-lite/reference.md

@@ -0,0 +1,16 @@
+# rcf-lite reference
+
+Reference pages on the Stravica docs site. The docs are the current source of truth for verb shapes, exit codes, and the packaged blueprint shelf; the local knowledge is deliberately link-led so it stays current as the docs move.
+
+- **CLI reference (every `rcf` verb, options, examples):** [https://stravica.ai/docs/rcf/reference/cli/](https://stravica.ai/docs/rcf/reference/cli/)
+- **CLI cheatsheet (the shortlist an operator or agent reaches for daily):** [https://stravica.ai/docs/rcf/reference/cli/cheatsheet/](https://stravica.ai/docs/rcf/reference/cli/cheatsheet/)
+- **Document types (PRD, REQ, US, AC, FBS, TS, TAC, TC, ADR, FRAG):** [https://stravica.ai/docs/rcf/reference/document-types/](https://stravica.ai/docs/rcf/reference/document-types/)
+- **Exit codes (what a non-zero exit from any `rcf` verb means):** [https://stravica.ai/docs/rcf/reference/exit-codes/](https://stravica.ai/docs/rcf/reference/exit-codes/)
+- **Blueprints shelf (the composable building blocks that ship in the box):** [https://stravica.ai/docs/rcf/reference/blueprints/](https://stravica.ai/docs/rcf/reference/blueprints/)
+
+## Related surfaces
+
+- **Add rcf to an existing repo (the guide, not a blueprint):** [https://stravica.ai/docs/rcf/guides/add-rcf-to-existing-repo/](https://stravica.ai/docs/rcf/guides/add-rcf-to-existing-repo/)
+- **Close the loop without a deploy (running the cycle without a live target):** [https://stravica.ai/docs/rcf/guides/close-the-loop-without-a-deploy/](https://stravica.ai/docs/rcf/guides/close-the-loop-without-a-deploy/)
+- **Kick the tyres by hand (a minimal manual walkthrough):** [https://stravica.ai/docs/rcf/guides/kick-the-tyres-by-hand/](https://stravica.ai/docs/rcf/guides/kick-the-tyres-by-hand/)
+- **Using the tree viewer (the audit surface for a running project):** [https://stravica.ai/docs/rcf/guides/using-the-tree-viewer/](https://stravica.ai/docs/rcf/guides/using-the-tree-viewer/)

package/dist/engineering-pa-types-engineering/knowledge/rcf-lite/wire-your-agent.md

@@ -0,0 +1,17 @@
+# Wire your agent into an rcf-lite project
+
+`rcf init` scaffolds the `rcf/` tree, registers the MCP server in the project-root `.mcp.json`, and writes the agent-instructions fragment into `CLAUDE.md` and `AGENTS.md` (an existing file is refreshed in place). One command sets an agent up to work through the RCF chain.
+
+The Stravica docs page for this walkthrough is the current source of truth:
+
+- **Wire your agent:** [https://stravica.ai/docs/rcf/wire-your-agent/](https://stravica.ai/docs/rcf/wire-your-agent/)
+- **Wiring alternatives (harness variants, non-Claude Code setups):** [https://stravica.ai/docs/rcf/guides/wiring-alternatives/](https://stravica.ai/docs/rcf/guides/wiring-alternatives/)
+- **CLI reference for the wiring verbs (`rcf init`, `rcf doctor`):** [https://stravica.ai/docs/rcf/reference/cli/](https://stravica.ai/docs/rcf/reference/cli/)
+
+## What the PA does at wiring time
+
+1. Confirm the deploy target before touching the stack. Read `create-a-small-app.md` for the numbered sequence.
+2. Install `rcf-lite` per project (not global), so different apps can pin different versions.
+3. Run `rcf init` from the project root. Answer the interactive project-name prompt only; everything else seeds as placeholders for the agent to elicit.
+4. Confirm the harness is wired: the `.mcp.json` entry, the `CLAUDE.md`/`AGENTS.md` fragment, and the `rcf/` tree are all present.
+5. Re-run `rcf init` on an existing project when you want the wiring refreshed; it leaves the tree alone and rewrites the harness fragment.