knoxis-helper 1.8.2 → 1.8.4

package/lib/active-session.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const FILENAME = 'active-session.json';
+
+function activeSessionPath(workspace) {
+  return path.join(workspace, '.knoxis', FILENAME);
+}
+
+/**
+ * Persist the in-progress pair-programming session so session-end can
+ * reference the same IDs (portal recorder, Claude resume, backend relay).
+ */
+function writeActiveSession(workspace, data) {
+  const fp = activeSessionPath(workspace);
+  fs.mkdirSync(path.dirname(fp), { recursive: true });
+  const payload = {
+    ...data,
+    updatedAt: new Date().toISOString()
+  };
+  fs.writeFileSync(fp, JSON.stringify(payload, null, 2), 'utf8');
+  return payload;
+}
+
+function readActiveSession(workspace) {
+  try {
+    const raw = fs.readFileSync(activeSessionPath(workspace), 'utf8');
+    return JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+}
+
+function clearActiveSession(workspace) {
+  try {
+    fs.unlinkSync(activeSessionPath(workspace));
+  } catch (_) {}
+}
+
+module.exports = {
+  writeActiveSession,
+  readActiveSession,
+  clearActiveSession
+};

package/lib/knoxis-interactive-pair.js

@@ -36,6 +36,7 @@ const os = require('os');
 const { SessionRecorder } = require('./session-recorder');
 const { scaffoldStateLayout } = require('./state-scaffold');
 const { syncSessionToPortal } = require('./portal-sync');
+const { writeActiveSession, readActiveSession, clearActiveSession } = require('./active-session');
 const kitTemplates = require('./templates');
 
 // === CONFIG ===
@@ -290,6 +291,24 @@ function readIdentityFromEnv() {
   };
 }
 
+function persistActiveSession(recorder, identity, extra = {}) {
+  if (!recorder || !identity || !identity.workspace) return;
+  try {
+    writeActiveSession(identity.workspace, {
+      claudeSessionId: SESSION_ID,
+      recordedSessionId: recorder.sessionId,
+      backendSessionId: process.env.KNOXIS_BACKEND_SESSION_ID || null,
+      operatorId: identity.userId || identity.engineerId || null,
+      startedAt: recorder.startedAt,
+      mode: extra.mode ?? null,
+      kitMode: extra.kitMode ?? null,
+      taskHint: extra.taskHint ?? null
+    });
+  } catch (e) {
+    console.warn('  Could not persist active session: ' + e.message);
+  }
+}
+
 // === STATE-FILE UPDATE PROMPT ===
 // Forces Claude to actually write docs/state/*.md before the session closes.
 // The QIG dashboard reads these files; without this step they stay as scaffold
@@ -365,6 +384,8 @@ async function finalizeSession(recorder) {
 async function runKitMode(kitMode, task, identity, scaffoldResult) {
   const archetype = process.env.KNOXIS_KIT_ARCHETYPE || null;
   const pattern = process.env.KNOXIS_KIT_PATTERN || null;
+  const closingSession = kitMode === 'session-end';
+  const activeSession = closingSession ? readActiveSession(identity.workspace) : null;
   let tpl;
   try {
     // feature-kickoff additionally consumes identity (userId, workspaceId,
@@ -379,7 +400,11 @@ async function runKitMode(kitMode, task, identity, scaffoldResult) {
       workspace: identity.workspace,
       userId: identity.userId,
       workspaceId: identity.workspaceId,
-      parentTaskId: (identity.taskIds && identity.taskIds.length) ? identity.taskIds[0] : null
+      parentTaskId: (identity.taskIds && identity.taskIds.length) ? identity.taskIds[0] : null,
+      activeSession,
+      // Auto-doc opt-in flows through env var since the interactive runner
+      // sources its identity from the QIG portal rather than CLI args.
+      integrate: process.env.KNOXIS_INTEGRATE === 'true' || process.env.KNOXIS_INTEGRATE === '1'
     });
   } catch (e) {
     console.error('Kit template error: ' + e.message);
@@ -406,6 +431,11 @@ async function runKitMode(kitMode, task, identity, scaffoldResult) {
   console.log('  Workspace: ' + identity.workspace);
   console.log('  Session:   ' + SESSION_ID);
   console.log('  Recorded:  ' + recorder.sessionId);
+  if (closingSession && activeSession) {
+    console.log('  Closing:   ' + (activeSession.recordedSessionId || activeSession.claudeSessionId || '(see .knoxis/active-session.json)'));
+  } else if (!closingSession) {
+    persistActiveSession(recorder, identity, { kitMode, taskHint: task || null });
+  }
   if (task) console.log('  Hint:      ' + task.substring(0, 100) + (task.length > 100 ? '...' : ''));
   if (scaffoldResult && (scaffoldResult.dirs.length || scaffoldResult.files.length)) {
     console.log('  Scaffolded: ' + (scaffoldResult.dirs.length + scaffoldResult.files.length) + ' new entries (CODING_RULES + docs/state/)');
@@ -436,6 +466,13 @@ async function runKitMode(kitMode, task, identity, scaffoldResult) {
   console.log('');
 
   await finalizeSession(recorder);
+  if (closingSession) {
+    try {
+      clearActiveSession(identity.workspace);
+    } catch (e) {
+      console.warn('  Could not clear active session: ' + e.message);
+    }
+  }
   process.exit(result.code || 0);
 }
 
@@ -492,6 +529,7 @@ async function main() {
   console.log('  Task:      ' + task.substring(0, 100) + (task.length > 100 ? '...' : ''));
   console.log('  Session:   ' + SESSION_ID);
   console.log('  Recorded:  ' + recorder.sessionId);
+  persistActiveSession(recorder, identity, { mode: 'interactive', taskHint: task });
   console.log('  Workspace: ' + identity.workspace);
   console.log('  Pair:      ' + (hasGroq ? 'Groq (' + GROQ_MODEL + ')' : 'Disabled (no GROQ_API_KEY)'));
   console.log('  Timeout:   ' + (MAX_PHASE_MS / 60000).toFixed(0) + ' min per phase');

package/lib/knoxis-local-agent.js

@@ -991,6 +991,7 @@ async function handleRequest(req, res) {
         if (portalUserId) kitEnv.KNOXIS_USER_ID = portalUserId;
         if (portalWorkspaceId) kitEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
         if (portalTaskIds && portalTaskIds.length) kitEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+        if (sessionId) kitEnv.KNOXIS_BACKEND_SESSION_ID = sessionId;
         command = buildEnvCommand(kitEnv, `node "${scriptPath}"`);
         mode = `kit:${kitMode}${archetype ? `/${archetype}` : ''}`;
         console.log(`🧰 Kit (interactive runner): ${mode} — ${scriptPath}`);
@@ -1024,6 +1025,7 @@ async function handleRequest(req, res) {
           if (portalTaskIds && portalTaskIds.length) interactiveEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
           if (productSlug) interactiveEnv.KNOXIS_PRODUCT_SLUG = productSlug;
           if (projectSlug) interactiveEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+          if (sessionId) interactiveEnv.KNOXIS_BACKEND_SESSION_ID = sessionId;
           command = buildEnvCommand(interactiveEnv, `node "${scriptPath}"`);
           mode = 'interactive';
           console.log(`🤝 Interactive mode: ${scriptPath}`);
@@ -1495,6 +1497,8 @@ function connectRelayWebSocket() {
             if (portalUserId) kitEnv.KNOXIS_USER_ID = portalUserId;
             if (portalWorkspaceId) kitEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
             if (portalTaskIds && portalTaskIds.length) kitEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+            const relaySessionId = typeof msg.sessionId === 'string' ? msg.sessionId : null;
+            if (relaySessionId) kitEnv.KNOXIS_BACKEND_SESSION_ID = relaySessionId;
             command = buildEnvCommand(kitEnv, `node "${scriptPath}"`);
             console.log(`   🧰 Kit (interactive runner): ${kitMode}${archetype ? `/${archetype}` : ''} — ${scriptPath}`);
           } else {
@@ -1533,6 +1537,8 @@ function connectRelayWebSocket() {
               if (portalTaskIds && portalTaskIds.length) interactiveEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
               if (productSlug) interactiveEnv.KNOXIS_PRODUCT_SLUG = productSlug;
               if (projectSlug) interactiveEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+              const relaySessionId = typeof msg.sessionId === 'string' ? msg.sessionId : null;
+              if (relaySessionId) interactiveEnv.KNOXIS_BACKEND_SESSION_ID = relaySessionId;
               command = buildEnvCommand(interactiveEnv, `node "${scriptPath}"`);
               console.log(`   🤝 Interactive mode: ${scriptPath}`);
             } else {

package/lib/knoxis-pair-program.js

@@ -8,6 +8,7 @@ const kitTemplates = require('./templates');
 const { scaffoldStateLayout, assertStateLayout } = require('./state-scaffold');
 const { syncSessionToPortal } = require('./portal-sync');
 const { SessionRecorder } = require('./session-recorder');
+const { writeActiveSession } = require('./active-session');
 
 // ===== RETRY CONFIGURATION =====
 // Can be overridden via environment variables
@@ -804,7 +805,11 @@ async function run() {
       pattern: recoveryPattern,
       productSlug: args['product-slug'] || null,
       projectSlug: args['project-slug'] || null,
-      workspace
+      workspace,
+      // Operator opt-in for auto-doc generation. When --integrate is passed
+      // alongside --mode feature-kickoff, the kickoff template appends a
+      // phase-integrate phase that the session-end ritual will run later.
+      integrate: Boolean(args.integrate)
     });
     scheduledSteps = [{
       key: tpl.key,
@@ -887,6 +892,22 @@ async function run() {
       safeExec,
       safeExecAsync
     });
+    if (mode !== 'session-end') {
+      try {
+        writeActiveSession(workspace, {
+          claudeSessionId: null,
+          recordedSessionId: recorder.sessionId,
+          backendSessionId: process.env.KNOXIS_BACKEND_SESSION_ID || null,
+          operatorId: userId || engineerId || null,
+          startedAt: recorder.startedAt,
+          mode: mode || 'pair-program',
+          kitMode: mode || null,
+          taskHint: task || null
+        });
+      } catch (e) {
+        console.warn(`Could not persist active session: ${e.message}`);
+      }
+    }
     console.log(`Recording: ON`);
     console.log('');
   }

package/lib/templates/feature-kickoff.js

@@ -8,6 +8,11 @@
 // docs/features/<slug>/. Multiple features can coexist; each is independently
 // trackable from the QIG dashboard via its manifest.json.
 //
+// Canonical structural constraints (slug pattern, phase counts, manifest shape)
+// live in ./kickoff-schema.json and are also consumed by the server-side
+// KickoffPrepService that turns meeting transcripts into kickoff-ready JSON.
+// Keep this file's prose in sync with that schema if you change the numbers.
+//
 // State machine (similar shape to resume.js, autonomous-first):
 //   A: docs/features/<slug>/ missing                        → write the roadmap
 //   B: directory exists with unanswered _(fill in)_ entries → wait
@@ -93,6 +98,36 @@ touches. Steps must be small enough to ship in one pair-program session.
 **Don't pad.** A 4-step feature is fine. A 30-step feature with 3 phases of
 filler is not.
 
+### Optional final phase: \`phase-integrate\` (operator opt-in)
+
+If the session header above includes \`Integrate: yes\`, append one extra
+phase as the **last phase** of the feature, with this exact shape (id is
+load-bearing — the auto-doc generator looks for it):
+
+\`\`\`json
+{
+  "id": "phase-integrate",
+  "title": "Integrate (auto-doc)",
+  "goal": "Generate the public-contract API doc and register it for the chatbot",
+  "done_when": "docs/features/<slug>/PUBLIC_API.md exists and the integration-docs index has been notified",
+  "status": "pending",
+  "steps": [
+    { "id": "phase-integrate-step-1", "action": "Generate PUBLIC_API.md from manifest + live OpenAPI", "touches": "docs/features/<slug>/PUBLIC_API.md", "status": "pending" },
+    { "id": "phase-integrate-step-2", "action": "POST the doc to the backend integration-docs index for vectorization", "touches": "/api/public/integration-docs/index", "status": "pending" }
+  ]
+}
+\`\`\`
+
+Do NOT include \`phase-integrate\` when the session header does not say
+\`Integrate: yes\`. This is opt-in only — features that don't ship a public
+contract should not have this phase, and adding it half-heartedly creates
+half-baked docs in the vector store.
+
+When the operator opts in, mirror the phase into ROADMAP.md (add it to the
+phases list) and PHASES.md (with the two checkbox steps). The session-end
+ritual auto-detects \`phase-integrate\` as the eligible-pending phase and runs
+the doc generator without an extra command.
+
 ## Step 4 — Capture genuine open questions only
 
 If something truly cannot be decided autonomously (missing API decision,
@@ -306,7 +341,8 @@ function buildFeatureKickoffPrompt({
   workspace,
   userId,
   workspaceId,
-  parentTaskId
+  parentTaskId,
+  integrate
 } = {}) {
   const header = ['Mode: feature-kickoff'];
   if (productSlug) header.push(`Product: ${productSlug}`);
@@ -315,6 +351,7 @@ function buildFeatureKickoffPrompt({
   if (userId) header.push(`User ID: ${userId}`);
   if (workspaceId) header.push(`Workspace ID: ${workspaceId}`);
   if (parentTaskId) header.push(`Parent task ID: ${parentTaskId}`);
+  if (integrate) header.push('Integrate: yes');
   if (taskDescription) header.push(`Feature description (use as-is for the title and summary):\n${taskDescription}`);
   const ctx = `Session context:\n${header.join('\n')}\n\n`;
   return ctx + FEATURE_KICKOFF_BODY;

package/lib/templates/index.js

@@ -2,6 +2,7 @@
 
 const kickoff = require('./kickoff');
 const featureKickoff = require('./feature-kickoff');
+const featureIntegrate = require('./integrate');
 const resume = require('./resume');
 const sessionEnd = require('./session-end');
 const recovery = require('./recovery');
@@ -10,6 +11,7 @@ const codingRuleset = require('./coding-ruleset');
 const MODES = {
   kickoff,
   'feature-kickoff': featureKickoff,
+  'feature-integrate': featureIntegrate,
   resume,
   'session-end': sessionEnd,
   recovery

package/lib/templates/integrate.js

@@ -0,0 +1,252 @@
+'use strict';
+
+// Feature Integrate — single-shot, autonomous (v1)
+//
+// Operator opt-in: a feature includes a phase with id "phase-integrate" at
+// kickoff time, signaling that this feature ships a public-contract surface.
+// When all preceding phases are marked "done" and phase-integrate is the
+// next-pending phase, this template generates docs/features/<slug>/PUBLIC_API.md
+// from the live OpenAPI spec + the feature's manifest, marks phase-integrate
+// done, and (when the backend is reachable) posts the doc to the vectorizer
+// at /api/public/integration-docs/index so the chatbot can serve it as
+// integration guidance.
+//
+// State machine:
+//   A: PUBLIC_API.md missing or feature manifest changed since last write → write the doc
+//   B: PUBLIC_API.md present and manifest unchanged                         → no-op (idempotent re-run)
+//   C: phase-integrate is not pending or prior phases incomplete            → halt with a one-line note
+
+const FEATURE_INTEGRATE_BODY = `# Feature Integrate (single-shot, autonomous)
+
+You are running in single-shot mode. You produce one response and the process
+exits. Your job is to take the operator's feature slug (in the session header
+above), generate \`docs/features/<slug>/PUBLIC_API.md\` from the live API
+surface, mark the feature's \`phase-integrate\` step done, and (best-effort)
+register the doc with the backend so it can be vectorized for the chatbot.
+
+This is **a doc generation pass** — do not change application code, controllers,
+or any file outside \`docs/features/<slug>/\`.
+
+## Step 0 — Resolve the feature slug
+
+The slug is in the session header (\`Feature slug: <slug>\`). If absent, abort
+with a one-line note: "Feature integrate requires --prompt <slug>."
+
+Verify \`docs/features/<slug>/\` exists and contains \`manifest.json\`. If not,
+abort: "No feature found at docs/features/<slug>/. Run feature-kickoff first."
+
+## Step 1 — Confirm the operator opted in
+
+Open \`docs/features/<slug>/manifest.json\`. Look for a phase with
+\`id: "phase-integrate"\`.
+
+- **Not found** → halt: "This feature did not opt into integrate phase. To
+  enable, re-run feature-kickoff with the --integrate flag, or hand-edit
+  manifest.json to add a phase with id 'phase-integrate'."
+- **Found and \`status: "done"\` already** → State B → check whether
+  \`PUBLIC_API.md\` exists. If yes, idempotent no-op: print "PUBLIC_API.md
+  already up to date." If no, treat as State A.
+- **Found, \`status: "pending"\`, prior phases all \`status: "done"\`** → State A.
+  Continue.
+- **Found, \`status: "pending"\`, prior phases NOT all done** → State C → halt:
+  "phase-integrate is not yet eligible — phases X, Y, Z still pending."
+
+## Step 2 — Identify the public surface this feature shipped
+
+From \`manifest.json\`, walk every \`phases[].steps[].touches\` value.
+
+Filter to **Java files under \`src/main/java/com/yourcompany/voice/controller/\`**
+or any file whose path contains \`/controller/\`. These are the candidates for
+the public surface.
+
+For each touched controller file:
+- Read its \`@RequestMapping\` base path.
+- Read its \`@PostMapping\`, \`@GetMapping\`, \`@PutMapping\`, \`@DeleteMapping\`
+  annotations to enumerate routes.
+- Note the request body shape (look for \`@RequestBody\`, \`@RequestParam\`,
+  \`@RequestPart\` types).
+- Note the return type and any \`@Operation(summary=...)\` Swagger annotation
+  for prose.
+
+If a step's \`touches\` field references a non-controller file (service, DTO,
+config), skip it. Only the public-contract surface goes in PUBLIC_API.md.
+
+If after filtering you have zero controllers, this feature does not ship a
+public contract — abort: "No controllers in manifest's touched files; nothing
+to document. Use a different doc kind for this feature."
+
+## Step 3 — Fetch the live OpenAPI spec (best effort)
+
+Hit \`http://localhost:8080/v3/api-docs\` (Spring's default) and parse the JSON.
+If the backend is not running locally, look for an env var \`OPENAPI_URL\` and
+use that. If neither is reachable, skip live OpenAPI and rely solely on the
+controller source you read in Step 2 — the doc just won't include exact
+response schemas, only the route + summary + request body shape.
+
+For each route from Step 2, look up the matching path in the OpenAPI spec
+(\`paths.<basePath><route>\`) and pull:
+- \`summary\` and \`description\`
+- request schema (\`requestBody.content."application/json".schema\`)
+- response schema (\`responses."200".content.*.schema\`)
+- error responses
+
+## Step 4 — Generate \`docs/features/<slug>/PUBLIC_API.md\`
+
+Use this skeleton, populated from Steps 2–3. Keep it tight; integrators will
+read this in 60 seconds.
+
+\`\`\`markdown
+---
+feature_slug: <slug>
+generated_at: <ISO date>
+api_kind: public-contract
+---
+
+# <Feature Title> — Public API
+
+<2–3 sentence summary from manifest.feature_title + manifest.proposedSummary
+or the feature's ROADMAP.md Summary section.>
+
+**Base URL (deployed):** \`<from PUBLIC_VOICE_API.md or operator-known\`
+
+## 60-second quickstart
+
+\\\`\\\`\\\`bash
+# <smallest curl that exercises the headline endpoint>
+\\\`\\\`\\\`
+
+## Endpoints
+
+| Path | Method | Use when |
+|---|---|---|
+<one row per route from Step 2-3>
+
+## Authentication
+
+<Same shared-key pattern as PUBLIC_VOICE_API.md if these endpoints sit behind
+PublicVoiceGuard, or whatever the controllers actually enforce.>
+
+## <One section per endpoint>
+
+### Request
+\\\`\\\`\\\`json
+<request schema, example values>
+\\\`\\\`\\\`
+
+### Response
+\\\`\\\`\\\`json
+<response schema, example values>
+\\\`\\\`\\\`
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+<rows>
+
+## Error reference
+
+<reuse the standard envelope; reference codes the controllers actually emit>
+
+## Limits and defaults
+
+<rate limits, concurrency caps, etc. if known>
+
+## Need anything
+
+<Match the footer style in docs/PUBLIC_VOICE_API.md.>
+\`\`\`
+
+**Don't pad.** If a section has nothing to say, leave it out. Match the tone
+of the existing \`docs/PUBLIC_VOICE_API.md\` (terse, integrator-focused, no
+filler).
+
+## Step 5 — Mark phase-integrate done in the manifest
+
+Update \`docs/features/<slug>/manifest.json\`:
+- The phase with \`id: "phase-integrate"\` → \`status: "done"\`
+- All steps within that phase → \`status: "done"\`
+- If \`current_phase\` was \`phase-integrate\`, advance it to \`null\` (or to
+  the next pending phase if any exist after integrate).
+
+Mirror the change into \`docs/features/<slug>/STATUS.md\` (check off the box).
+Mirror into \`docs/features/<slug>/PHASES.md\` (\`- [x]\` for the integrate
+steps).
+
+## Step 6 — Best-effort: register the doc with the backend vectorizer
+
+POST the generated markdown to the backend's integration-docs index endpoint:
+
+\`\`\`bash
+curl -s -X POST "$BACKEND/api/public/integration-docs/index" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Tenant-Id: $TENANT" \\
+  -H "X-Public-Voice-Key: $KEY" \\
+  -d '{"slug": "<slug>", "markdown": "<contents>"}'
+\`\`\`
+
+Read \`BACKEND\` from env or default to \`http://localhost:8080\`. Read
+\`TENANT\` from env (\`KNOXIS_TENANT_ID\`) — if missing, skip vectorization
+with a one-line note "Skipped vectorization: KNOXIS_TENANT_ID not set."
+Read \`KEY\` from env \`PUBLIC_VOICE_API_SHARED_KEY\` (optional).
+
+If the curl returns non-2xx, do not fail — the doc was still written to disk.
+Print one line: "Vectorize call returned <code>; doc was generated. The
+operator can re-run vectorization manually."
+
+## Step 7 — Output for the operator
+
+End with a copyable block:
+
+\`\`\`
+Feature integrate complete: <slug>
+
+Files written:
+  docs/features/<slug>/PUBLIC_API.md
+  docs/features/<slug>/manifest.json (phase-integrate → done)
+  docs/features/<slug>/STATUS.md (checkbox)
+  docs/features/<slug>/PHASES.md (checkboxes)
+
+Vectorization: <success | skipped | failed>
+
+Next: the doc is ready to share with integrators and (when registered) to
+serve via the chatbot's "I need a feature for X" intent.
+\`\`\`
+
+## Non-negotiables
+
+- Write \`PUBLIC_API.md\` to disk. Do not describe what you would write.
+- Match the tone and structure of \`docs/PUBLIC_VOICE_API.md\` and
+  \`docs/PUBLIC_SPEAKER_API.md\` — these are the canonical examples.
+- Keep \`manifest.json\` consistent with the three MD files at all times.
+- Do not modify application code (no edits to anything outside
+  \`docs/features/<slug>/\`).
+- One feature per run. The slug is final for this run.
+- Idempotent. Re-running with PUBLIC_API.md already up to date is a no-op.
+
+---
+
+`;
+
+function buildFeatureIntegratePrompt({
+  taskDescription,
+  productSlug,
+  projectSlug,
+  workspace,
+  userId,
+  workspaceId
+} = {}) {
+  const header = ['Mode: feature-integrate'];
+  if (productSlug) header.push(`Product: ${productSlug}`);
+  if (projectSlug) header.push(`Project: ${projectSlug}`);
+  if (workspace) header.push(`Workspace: ${workspace}`);
+  if (userId) header.push(`User ID: ${userId}`);
+  if (workspaceId) header.push(`Workspace ID: ${workspaceId}`);
+  if (taskDescription) header.push(`Feature slug: ${taskDescription}`);
+  const ctx = `Session context:\n${header.join('\n')}\n\n`;
+  return ctx + FEATURE_INTEGRATE_BODY;
+}
+
+module.exports = {
+  title: 'Feature Integrate',
+  body: FEATURE_INTEGRATE_BODY,
+  buildPrompt: buildFeatureIntegratePrompt
+};

package/lib/templates/kickoff-schema.json

@@ -0,0 +1,75 @@
+{
+  "version": "1.0",
+  "description": "Single source of truth for the feature-kickoff phase shape. Shared by scripts/knoxis-helper/lib/templates/feature-kickoff.js (operator-facing prompt) and src/main/java/com/yourcompany/voice/service/kickoffprep/* (server-side meeting → kickoff-prep generator). Both read these constraints to keep the JSON shape consistent and prevent drift.",
+
+  "slug": {
+    "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
+    "maxLength": 40,
+    "rules": [
+      "Lowercase alphanumeric and dashes only.",
+      "Max 40 characters.",
+      "Semantically descriptive of the feature.",
+      "Do not include the words 'feature' or 'task'."
+    ],
+    "examples": [
+      { "description": "Add real-time notification toasts", "slug": "realtime-notification-toasts" },
+      { "description": "Replace polling with SSE on the dashboard", "slug": "dashboard-sse-replacement" }
+    ]
+  },
+
+  "phases": {
+    "minCount": 3,
+    "maxCount": 6,
+    "stepsPerPhase": { "min": 2, "max": 6 },
+    "rules": [
+      "Phases run sequentially.",
+      "Each phase has a clear 'done when' criterion.",
+      "Each step is one imperative-voice action plus the file(s) or surface it touches.",
+      "Steps must be small enough to ship in one pair-program session.",
+      "Don't pad. A 4-step feature is fine. A 30-step feature with 3 phases of filler is not."
+    ],
+    "defaultShape": [
+      { "title": "Discovery",      "goal": "Read existing code, find integration points, list constraints" },
+      { "title": "Design",         "goal": "Data model / API contract / UI shape decisions" },
+      { "title": "Implementation", "goal": "Commit-sized steps, each touching named files" },
+      { "title": "Testing",        "goal": "Unit / integration / manual coverage" },
+      { "title": "Rollout",        "goal": "Feature flag, docs, telemetry, deprecations" }
+    ]
+  },
+
+  "openQuestions": {
+    "guidance": "Capture genuine open questions only. Most 'questions' are decisions you should make and capture in DECISIONS instead. If you write more than 3 pending questions you are over-using this.",
+    "softMax": 3
+  },
+
+  "manifestShape": {
+    "feature_slug": "string (matches slug.pattern)",
+    "feature_title": "string",
+    "parent_task_id": "string | null",
+    "workspace_id": "string | null",
+    "user_id": "string | null",
+    "product_slug": "string | null",
+    "project_slug": "string | null",
+    "kicked_off_at": "ISO timestamp",
+    "status": "planning | blocked | in-progress | done",
+    "current_phase": "string (phase id, e.g. phase-1)",
+    "phases": [
+      {
+        "id": "string (phase-{n})",
+        "title": "string",
+        "goal": "string",
+        "done_when": "string",
+        "status": "pending | in-progress | done",
+        "steps": [
+          {
+            "id": "string (phase-{n}-step-{m})",
+            "action": "string (imperative)",
+            "touches": "string (file or surface)",
+            "status": "pending | in-progress | done"
+          }
+        ]
+      }
+    ],
+    "definition_of_done": ["string"]
+  }
+}

package/lib/templates/session-end.js

@@ -28,9 +28,11 @@ Coaching reminders that apply throughout:
 
 Before starting, confirm:
 - **Operator ID** for this session (should match what was set in resume Step 0).
-- **Session ID** held since session start.
+- **Session ID** for the working session you are closing (not the session-end invocation).
 
-If you're unsure of either, surface it before proceeding. Author tags on artifacts must be accurate.
+If **Session context** above includes a **Working session** block, use those IDs directly — do not ask the operator to confirm them. Use **Portal recorded session** as \`session_id\` in the Step 9 SESSION record and in \`last_session_id\` frontmatter unless the framework calls for a new semantic slug for this closeout. Use **Operator ID** from that block for author tags.
+
+If no Working session block is present and you're unsure of either ID, surface it before proceeding. Author tags on artifacts must be accurate.
 
 ---
 
@@ -345,6 +347,68 @@ For specific archetypes, populate \`archetype_specific_data\`:
 
 Show me. Ask: "Paste this into the portal, or wait for portal MCP to upload it automatically (if live)?"
 
+## Step 9.5 — Auto-integrate eligible features (opt-in features only)
+
+**Orientation:** "If any feature in this project opted into auto-doc generation
+by including a \`phase-integrate\` phase, and that phase is now eligible to
+run, generate its public API doc here so the next session opens with it
+already shipped."
+
+For each \`docs/features/*/manifest.json\`, check whether **all three** are true:
+
+1. A phase exists with \`id: "phase-integrate"\`.
+2. That phase's \`status\` is \`"pending"\`.
+3. Every phase before it has \`status: "done"\`.
+
+If no manifest meets all three, say "No features are eligible for auto-integrate
+this session." and skip to Step 10.
+
+For each eligible feature, run the integrate playbook autonomously (you do not
+need a separate command — execute the steps inline now):
+
+1. Read the controllers listed in the feature's \`phases[].steps[].touches\` —
+   anything under \`src/main/java/com/yourcompany/voice/controller/\`.
+2. (Best effort) Fetch \`http://localhost:8080/v3/api-docs\` to enrich with live
+   request/response schemas. If unreachable, skip and use the controller source
+   directly. Don't fail the step on this.
+3. Generate \`docs/features/<slug>/PUBLIC_API.md\` matching the structure and
+   tone of \`docs/PUBLIC_VOICE_API.md\` and \`docs/PUBLIC_SPEAKER_API.md\`.
+   Sections: title + 2-3 sentence summary, 60-second quickstart, endpoint
+   table, authentication, per-endpoint request/response, error reference,
+   limits, footer.
+4. Update the feature's \`manifest.json\`: \`phase-integrate\` → \`status: "done"\`,
+   each step within → \`status: "done"\`, advance \`current_phase\` past it.
+5. Mirror the status changes into \`docs/features/<slug>/STATUS.md\` and
+   \`docs/features/<slug>/PHASES.md\` (check the boxes).
+6. **Best-effort vectorization.** If \`KNOXIS_TENANT_ID\` is set in the
+   environment, POST the generated markdown to:
+
+   \`\`\`
+   POST $BACKEND/api/public/integration-docs/index
+   Headers: Content-Type: application/json
+            X-Tenant-Id: $KNOXIS_TENANT_ID
+            X-Public-Voice-Key: $PUBLIC_VOICE_API_SHARED_KEY (if set)
+   Body:    { "slug": "<slug>", "markdown": "<file contents>" }
+   \`\`\`
+
+   Default \`BACKEND\` to \`http://localhost:8080\`. If the call fails with a
+   non-2xx, **don't fail the session** — note "Vectorization deferred (HTTP
+   <code>); operator can re-run via knoxis-helper --mode feature-integrate
+   --prompt <slug>." and move on. The doc is on disk regardless.
+
+For each feature you processed, output:
+
+\`\`\`
+Auto-integrated: <slug>
+  PUBLIC_API.md: <created | refreshed>
+  manifest.json: phase-integrate → done
+  Vectorization:  <success | skipped (no tenant) | deferred (HTTP <code>)>
+\`\`\`
+
+Do not run integrate logic on features where the conditions aren't met. Don't
+add a \`phase-integrate\` to features that didn't have one — operator opt-in
+is sticky.
+
 ## Step 10 — Final summary
 
 Print a one-paragraph summary:
@@ -378,7 +442,15 @@ Otherwise, end with: "Ready to close. Have a good one."
 
 **Begin now.** Start with the preamble.`;
 
-function buildSessionEndPrompt({ archetype, taskDescription, productSlug, projectSlug, workspace } = {}) {
+function buildSessionEndPrompt({
+  archetype,
+  taskDescription,
+  productSlug,
+  projectSlug,
+  workspace,
+  activeSession,
+  userId
+} = {}) {
   const header = [];
   header.push('Mode: session-end');
   if (archetype) header.push(`Archetype: ${archetype}`);
@@ -386,6 +458,24 @@ function buildSessionEndPrompt({ archetype, taskDescription, productSlug, projec
   if (projectSlug) header.push(`Project: ${projectSlug}`);
   if (workspace) header.push(`Workspace: ${workspace}`);
   if (taskDescription) header.push(`Session task: ${taskDescription}`);
+
+  const work = activeSession || null;
+  const operatorId = (work && work.operatorId) || userId || null;
+  if (work) {
+    header.push('');
+    header.push('Working session (close this one — ignore the session-end runner banner IDs):');
+    if (work.recordedSessionId) header.push(`  Portal recorded session: ${work.recordedSessionId}`);
+    if (work.claudeSessionId) header.push(`  Claude session: ${work.claudeSessionId}`);
+    if (work.collabSessionId) header.push(`  Collab session: ${work.collabSessionId}`);
+    if (work.backendSessionId) header.push(`  Knoxis backend session: ${work.backendSessionId}`);
+    if (operatorId) header.push(`  Operator ID: ${operatorId}`);
+    if (work.startedAt) header.push(`  Started at: ${work.startedAt}`);
+    if (work.kitMode) header.push(`  Kit mode: ${work.kitMode}`);
+    if (work.mode) header.push(`  Runner mode: ${work.mode}`);
+  } else if (operatorId) {
+    header.push(`Operator ID (from portal): ${operatorId}`);
+  }
+
   const ctx = `Session context:\n${header.join('\n')}\n\n`;
   return ctx + SESSION_END_BODY;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knoxis-helper",
-  "version": "1.8.2",
+  "version": "1.8.4",
   "description": "Local helper for Knoxis pair programming - connects your machine to Knoxis on qig.ai",
   "bin": {
     "knoxis-helper": "./bin/knoxis-helper.js"