@amistio/cli 0.1.12 → 0.1.14

package/dist/index.js

@@ -4,7 +4,7 @@
 import { createHash as createHash7, randomUUID } from "node:crypto";
 import { writeFile as writeFile9 } from "node:fs/promises";
 import os7 from "node:os";
-import path13 from "node:path";
+import path14 from "node:path";
 import { Command } from "commander";
 
 // ../shared/src/schemas.ts
@@ -24,6 +24,12 @@ var itemTypeSchema = z.enum([
   "securityScan",
   "securityFinding",
   "securityPostureSnapshot",
+  "appEvaluationScan",
+  "appEvaluationFinding",
+  "projectContextMap",
+  "projectContextRefresh",
+  "projectSystemDiagram",
+  "contextMiss",
   "syncCursor",
   "syncConflict",
   "workItem",
@@ -48,6 +54,8 @@ var documentTypeSchema = z.enum([
   "prompt",
   "workflow"
 ]);
+var documentContentFormatSchema = z.enum(["markdown", "html"]);
+var artifactFormatPreferenceSchema = z.enum(["markdown", "html", "both", "auto"]);
 var syncStateSchema = z.enum([
   "draft",
   "approved",
@@ -70,7 +78,23 @@ var workStatusSchema = z.enum([
 ]);
 var sourceSchema = z.enum(["web", "repo", "generated", "runner"]);
 var executionModeSchema = z.enum(["localRunner", "cloudSandbox"]);
-var workKindSchema = z.enum(["brainGeneration", "implementation", "planRevision", "assistantQuestion", "impactPreview", "issueDiagnosis", "securityPostureScan"]);
+var workKindSchema = z.enum(["brainGeneration", "implementation", "planRevision", "assistantQuestion", "impactPreview", "issueDiagnosis", "securityPostureScan", "appEvaluationScan", "projectContextRefresh"]);
+var implementationHandoffStatusSchema = z.enum(["notStarted", "noChanges", "prReady", "blocked", "failed"]);
+var implementationHandoffCleanupStatusSchema = z.enum(["notApplicable", "pending", "completed", "failed"]);
+var implementationHandoffSchema = z.object({
+  provider: z.string().trim().min(1).max(80).optional(),
+  status: implementationHandoffStatusSchema,
+  baseBranch: z.string().trim().min(1).max(200).optional(),
+  headBranch: z.string().trim().min(1).max(200).optional(),
+  remoteName: z.string().trim().min(1).max(80).optional(),
+  commitSha: z.string().trim().min(7).max(64).optional(),
+  prNumber: z.number().int().positive().optional(),
+  prUrl: z.string().trim().url().max(500).optional(),
+  cleanupStatus: implementationHandoffCleanupStatusSchema.optional(),
+  cleanupMessage: z.string().trim().min(1).max(600).optional(),
+  message: z.string().trim().min(1).max(600).optional(),
+  error: z.string().trim().min(1).max(1200).optional()
+}).strict();
 var generatedDraftStatusSchema = z.enum(["queued", "generating", "reviewing", "approved", "rejected", "changesRequested", "failed"]);
 var assistantQuestionModeSchema = z.enum(["brainOnly", "sourceAware"]);
 var impactRiskLevelSchema = z.enum(["low", "medium", "high", "critical"]);
@@ -80,12 +104,19 @@ var issueSeveritySchema = z.enum(["low", "medium", "high", "critical"]);
 var issueStatusSchema = z.enum(["queued", "diagnosing", "analysisReady", "approved", "changesRequested", "rejected", "implementationQueued", "implemented", "failed"]);
 var issueApprovalStateSchema = z.enum(["proposed", "approved", "changesRequested", "rejected", "implemented", "blocked"]);
 var securityScanStatusSchema = z.enum(["queued", "running", "completed", "failed", "stale", "skipped"]);
-var securityScanSourceSchema = z.enum(["nightly", "manual"]);
+var securityScanSourceSchema = z.enum(["nightly", "manual", "runner"]);
 var securityFindingCategorySchema = z.enum(["owasp", "dependency", "supplyChain", "secretHygiene", "authentication", "authorization", "tenantIsolation", "headers", "redirects", "csrf", "cors", "ciCd", "logging", "runnerBoundary", "other"]);
 var securityFindingSeveritySchema = z.enum(["info", "low", "medium", "high", "critical"]);
 var securityFindingConfidenceSchema = z.enum(["low", "medium", "high"]);
 var securityFindingStatusSchema = z.enum(["open", "planReady", "approved", "changesRequested", "dismissed", "acceptedRisk", "remediationQueued", "resolved", "failed"]);
 var securityApprovalStateSchema = z.enum(["proposed", "approved", "changesRequested", "dismissed", "acceptedRisk", "implemented", "blocked"]);
+var appEvaluationScanStatusSchema = z.enum(["queued", "running", "completed", "failed", "stale", "skipped"]);
+var appEvaluationFindingCategorySchema = z.enum(["verification", "productDrift", "planCleanup", "promptRot", "missingMemory", "releaseReadiness", "ux", "accessibility", "performance", "reliability", "securityPosture", "other"]);
+var appEvaluationFindingSeveritySchema = z.enum(["info", "low", "medium", "high", "critical"]);
+var appEvaluationFindingConfidenceSchema = z.enum(["low", "medium", "high"]);
+var appEvaluationFindingStatusSchema = z.enum(["open", "planReady", "approved", "changesRequested", "dismissed", "acceptedRisk", "implementationQueued", "resolved", "failed"]);
+var appEvaluationApprovalStateSchema = z.enum(["proposed", "approved", "changesRequested", "dismissed", "acceptedRisk", "implemented", "blocked"]);
+var appEvaluationPlanLifecycleActionSchema = z.enum(["createPlan", "updatePlan", "markCompleted", "markImplemented", "markSuperseded", "markBlocked", "archive", "keepActive", "none"]);
 var activityEventTypeSchema = z.enum([
   "commandSubmitted",
   "generationQueued",
@@ -117,6 +148,22 @@ var activityEventTypeSchema = z.enum([
   "securityFindingReviewed",
   "securityRemediationPlanCreated",
   "securityRemediationQueued",
+  "appEvaluationQueued",
+  "appEvaluationStarted",
+  "appEvaluationCompleted",
+  "appEvaluationFailed",
+  "appEvaluationFindingOpened",
+  "appEvaluationFindingReviewed",
+  "appEvaluationPlanCreated",
+  "appEvaluationImplementationQueued",
+  "projectContextRefreshQueued",
+  "projectContextRefreshStarted",
+  "projectContextRefreshCompleted",
+  "projectContextRefreshFailed",
+  "projectContextMissRecorded",
+  "projectSystemDiagramGenerated",
+  "projectSystemDiagramReviewed",
+  "projectSystemDiagramMissRecorded",
   "handoffExported"
 ]);
 var activityEventActorSchema = z.enum(["webUser", "runner", "cli", "system"]);
@@ -131,6 +178,7 @@ var activityMetadataValueSchema = z.union([
 var activityMetadataSchema = z.record(z.string().min(1).max(80), activityMetadataValueSchema).default({});
 var generatedBrainArtifactSchema = z.object({
   documentType: documentTypeSchema,
+  contentFormat: documentContentFormatSchema.default("markdown"),
   title: z.string().trim().min(1),
   repoPath: z.string().trim().min(1),
   content: z.string().min(1)
@@ -243,6 +291,7 @@ var organizationWorkspaceScopeSchema = z.object({
   kind: z.literal("organization"),
   accountId: z.string().min(1),
   organizationId: z.string().min(1),
+  userId: z.string().min(1).optional(),
   organizationSlug: z.string().trim().min(1).optional(),
   organizationRole: z.string().trim().min(1).optional(),
   label: z.string().trim().min(1).default("Organization workspace")
@@ -282,6 +331,7 @@ var projectItemSchema = baseItemSchema.extend({
   name: z.string().min(1),
   slug: z.string().min(1),
   description: z.string().optional(),
+  artifactFormatPreference: artifactFormatPreferenceSchema.optional(),
   status: projectStatusSchema.default("active"),
   archivedAt: isoDateTimeSchema.optional(),
   archivedByUserId: z.string().min(1).optional(),
@@ -302,6 +352,7 @@ var repositoryLinkItemSchema = baseItemSchema.extend({
   linkSource: repositoryLinkSourceSchema.optional(),
   cloneStatus: repositoryCloneStatusSchema.optional(),
   autoSyncEnabled: z.boolean().optional(),
+  appEvaluationEnabled: z.boolean().optional(),
   lastValidatedAt: isoDateTimeSchema.optional(),
   status: z.enum(["active", "revoked"]).default("active")
 });
@@ -310,6 +361,7 @@ var brainDocumentItemSchema = baseItemSchema.extend({
   projectId: z.string().min(1),
   documentId: z.string().min(1),
   documentType: documentTypeSchema,
+  contentFormat: documentContentFormatSchema.default("markdown"),
   title: z.string().min(1),
   status: z.string().min(1),
   repoPath: z.string().min(1),
@@ -369,6 +421,10 @@ var workItemSchema = baseItemSchema.extend({
   issueId: z.string().min(1).optional(),
   securityScanId: z.string().min(1).optional(),
   securityFindingId: z.string().min(1).optional(),
+  appEvaluationScanId: z.string().min(1).optional(),
+  appEvaluationFindingId: z.string().min(1).optional(),
+  projectContextRefreshId: z.string().min(1).optional(),
+  contextMissId: z.string().min(1).optional(),
   repositoryLinkId: z.string().min(1).optional(),
   reviewThreadId: z.string().min(1).optional(),
   reviewDocumentId: z.string().min(1).optional(),
@@ -376,6 +432,7 @@ var workItemSchema = baseItemSchema.extend({
   reviewMessageId: z.string().min(1).optional(),
   assistantMessageId: z.string().min(1).optional(),
   assistantQuestionMode: assistantQuestionModeSchema.optional(),
+  artifactFormatPreference: artifactFormatPreferenceSchema.optional(),
   impactReportId: z.string().min(1).optional(),
   impactDocumentId: z.string().min(1).optional(),
   impactDocumentRevision: z.number().int().nonnegative().optional(),
@@ -401,6 +458,7 @@ var workItemSchema = baseItemSchema.extend({
   toolSessionId: z.string().min(1).optional(),
   sessionDecision: sessionDecisionSchema.optional(),
   sessionDecisionReason: z.string().min(1).optional(),
+  implementationHandoff: implementationHandoffSchema.optional(),
   lastStatusMessage: z.string().optional(),
   lastStatusAt: isoDateTimeSchema
 });
@@ -495,6 +553,7 @@ var runnerExecutionLogItemSchema = baseItemSchema.extend({
   toolSessionId: z.string().min(1).optional(),
   sessionDecision: sessionDecisionSchema.optional(),
   sessionDecisionReason: z.string().min(1).optional(),
+  implementationHandoff: implementationHandoffSchema.optional(),
   message: z.string().optional(),
   error: z.string().optional()
 });
@@ -591,7 +650,7 @@ var assistantAnswerResultSchema = z.object({
   summary: z.string().optional()
 });
 var knowledgeSearchScopeSchema = z.enum(["project", "organization"]);
-var knowledgeSourceTypeSchema = z.enum(["brainDocument", "generatedArtifact", "runnerSummary", "knowledgeEntity", "knowledgeRelation"]);
+var knowledgeSourceTypeSchema = z.enum(["brainDocument", "generatedArtifact", "runnerSummary", "knowledgeEntity", "knowledgeRelation", "projectContextMap", "projectContextSlice", "projectSystemDiagram", "projectSystemDiagramNode", "projectSystemDiagramEdge"]);
 var knowledgeChunkStatusSchema = z.enum(["approved", "synced", "stale"]);
 var knowledgeEntityTypeSchema = z.enum(["project", "system", "component", "domain", "tool", "decision", "feature", "risk", "team", "workflow", "unknown"]);
 var knowledgeRelationTypeSchema = z.enum(["uses", "depends_on", "decides", "supersedes", "touches", "blocks", "implements", "mentions"]);
@@ -703,6 +762,221 @@ var knowledgeDiagramResultSchema = z.object({
   freshness: knowledgeIndexFreshnessSchema,
   warnings: z.array(z.string().trim().min(1).max(600)).default([])
 });
+var projectContextSliceKindSchema = z.enum(["overview", "architecture", "domain", "data", "api", "frontend", "backend", "cli", "workflow", "operations", "security", "testing", "unknown"]);
+var projectContextFreshnessSchema = z.enum(["fresh", "stale", "partial", "missing"]);
+var projectContextMapStatusSchema = z.enum(["draft", "proposed", "approved", "stale", "archived"]);
+var projectContextRefreshStatusSchema = z.enum(["queued", "running", "completed", "failed", "skipped"]);
+var contextMissStatusSchema = z.enum(["open", "resolved", "dismissed"]);
+var projectContextRepoPathSchema = z.string().trim().min(1).max(300).refine((value) => {
+  if (value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value)) {
+    return false;
+  }
+  return !value.split(/[\\/]+/).includes("..");
+}, "Path must be repository-relative without traversal");
+var projectContextCoverageSchema = z.object({
+  status: projectContextFreshnessSchema.default("missing"),
+  sliceCount: z.number().int().nonnegative().default(0),
+  staleSliceCount: z.number().int().nonnegative().default(0),
+  missingAreas: z.array(z.string().trim().min(1).max(160)).default([]),
+  warnings: z.array(z.string().trim().min(1).max(300)).default([])
+});
+var defaultProjectContextCoverage = { status: "missing", sliceCount: 0, staleSliceCount: 0, missingAreas: [], warnings: [] };
+var projectContextSliceSchema = z.object({
+  sliceId: z.string().trim().min(1).max(160),
+  kind: projectContextSliceKindSchema.default("unknown"),
+  title: z.string().trim().min(1).max(200),
+  summary: z.string().trim().min(1).max(4e3),
+  repoPaths: z.array(projectContextRepoPathSchema).max(80).default([]),
+  ownerHints: z.array(z.string().trim().min(1).max(160)).max(20).default([]),
+  tags: z.array(z.string().trim().min(1).max(80)).max(30).default([]),
+  citations: z.array(assistantCitationSchema).default([]),
+  dependsOn: z.array(z.string().trim().min(1).max(160)).max(50).default([]),
+  freshness: projectContextFreshnessSchema.default("fresh"),
+  confidence: z.number().min(0).max(1).default(0.6),
+  contentHash: z.string().trim().min(1).max(160).optional(),
+  lastVerifiedAt: isoDateTimeSchema.optional()
+});
+var projectContextEntitySchema = z.object({
+  entityId: z.string().trim().min(1).max(200),
+  name: z.string().trim().min(1).max(200),
+  entityType: knowledgeEntityTypeSchema.default("unknown"),
+  summary: z.string().trim().min(1).max(1200).optional(),
+  aliases: z.array(z.string().trim().min(1).max(200)).default([]),
+  sliceIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  citations: z.array(assistantCitationSchema).default([]),
+  confidence: z.number().min(0).max(1).default(0.6)
+});
+var projectContextRelationSchema = z.object({
+  relationId: z.string().trim().min(1).max(200),
+  relationType: knowledgeRelationTypeSchema.default("mentions"),
+  fromId: z.string().trim().min(1).max(200),
+  toId: z.string().trim().min(1).max(200),
+  summary: z.string().trim().min(1).max(1200),
+  citations: z.array(assistantCitationSchema).default([]),
+  confidence: z.number().min(0).max(1).default(0.6)
+});
+var projectSystemDiagramStatusSchema = z.enum(["draft", "proposed", "approved", "stale", "archived"]);
+var projectSystemDiagramViewKindSchema = z.enum(["wholeSystem", "projectBrainLifecycle", "contextRefresh", "runtimeTopology", "featureFlow"]);
+var projectSystemDiagramNodeKindSchema = z.enum(["actor", "app", "api", "cli", "runner", "dataStore", "searchIndex", "authBoundary", "repository", "externalService", "workflow", "component", "unknown"]);
+var projectSystemDiagramGroupKindSchema = z.enum(["boundary", "lane", "group"]);
+var projectSystemDiagramDirectionSchema = z.enum(["TD", "LR"]);
+var projectSystemDiagramNodeSchema = z.object({
+  nodeId: z.string().trim().min(1).max(200),
+  label: z.string().trim().min(1).max(120),
+  kind: projectSystemDiagramNodeKindSchema.default("unknown"),
+  summary: z.string().trim().min(1).max(1200).optional(),
+  groupId: z.string().trim().min(1).max(160).optional(),
+  lane: z.string().trim().min(1).max(120).optional(),
+  sliceIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  entityIds: z.array(z.string().trim().min(1).max(200)).default([]),
+  citations: z.array(assistantCitationSchema).min(1),
+  confidence: z.number().min(0).max(1).default(0.6),
+  freshness: projectContextFreshnessSchema.default("fresh")
+});
+var projectSystemDiagramEdgeSchema = z.object({
+  edgeId: z.string().trim().min(1).max(220),
+  fromNodeId: z.string().trim().min(1).max(200),
+  toNodeId: z.string().trim().min(1).max(200),
+  relationType: knowledgeRelationTypeSchema.default("mentions"),
+  label: z.string().trim().min(1).max(120).optional(),
+  summary: z.string().trim().min(1).max(1200),
+  citations: z.array(assistantCitationSchema).min(1),
+  confidence: z.number().min(0).max(1).default(0.6),
+  freshness: projectContextFreshnessSchema.default("fresh")
+});
+var projectSystemDiagramGroupSchema = z.object({
+  groupId: z.string().trim().min(1).max(160),
+  label: z.string().trim().min(1).max(120),
+  kind: projectSystemDiagramGroupKindSchema.default("group"),
+  summary: z.string().trim().min(1).max(1200).optional(),
+  citations: z.array(assistantCitationSchema).default([])
+});
+var projectSystemDiagramViewSchema = z.object({
+  viewId: z.string().trim().min(1).max(160),
+  kind: projectSystemDiagramViewKindSchema,
+  title: z.string().trim().min(1).max(160),
+  summary: z.string().trim().min(1).max(1200),
+  nodeIds: z.array(z.string().trim().min(1).max(200)).min(1),
+  edgeIds: z.array(z.string().trim().min(1).max(220)).default([]),
+  groupIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  mermaid: z.string().trim().min(1).max(12e3),
+  warnings: z.array(z.string().trim().min(1).max(600)).default([]),
+  freshness: projectContextFreshnessSchema.default("fresh")
+});
+var projectSystemDiagramGraphManifestSchema = z.object({
+  manifestId: z.string().trim().min(1).max(200),
+  layoutVersion: z.number().int().positive().default(1),
+  direction: projectSystemDiagramDirectionSchema.default("LR"),
+  nodes: z.array(projectSystemDiagramNodeSchema).min(1),
+  edges: z.array(projectSystemDiagramEdgeSchema).default([]),
+  groups: z.array(projectSystemDiagramGroupSchema).default([]),
+  views: z.array(projectSystemDiagramViewSchema).min(1),
+  citations: z.array(assistantCitationSchema).default([]),
+  unknowns: z.array(z.string().trim().min(1).max(300)).default([]),
+  warnings: z.array(z.string().trim().min(1).max(600)).default([])
+});
+var projectSystemDiagramItemSchema = baseItemSchema.extend({
+  type: z.literal("projectSystemDiagram"),
+  projectId: z.string().min(1),
+  projectSystemDiagramId: z.string().min(1),
+  version: z.number().int().positive(),
+  status: projectSystemDiagramStatusSchema,
+  source: sourceSchema.default("generated"),
+  repositoryLinkId: z.string().min(1).optional(),
+  projectContextMapId: z.string().min(1),
+  projectContextMapVersion: z.number().int().positive(),
+  sourceBrainRevision: z.number().int().nonnegative().optional(),
+  summary: z.string().trim().min(1).max(4e3),
+  graph: projectSystemDiagramGraphManifestSchema,
+  coverage: projectContextCoverageSchema.default(defaultProjectContextCoverage),
+  mermaid: z.string().trim().min(1).max(12e3),
+  approvedByUserId: z.string().min(1).optional(),
+  approvedAt: isoDateTimeSchema.optional(),
+  generatedAt: isoDateTimeSchema,
+  supersedesDiagramId: z.string().min(1).optional(),
+  error: z.string().max(1e3).optional()
+});
+var projectContextMapItemSchema = baseItemSchema.extend({
+  type: z.literal("projectContextMap"),
+  projectId: z.string().min(1),
+  projectContextMapId: z.string().min(1),
+  version: z.number().int().positive(),
+  status: projectContextMapStatusSchema,
+  source: sourceSchema.default("runner"),
+  repositoryLinkId: z.string().min(1).optional(),
+  refreshId: z.string().min(1).optional(),
+  summary: z.string().trim().min(1).max(4e3),
+  slices: z.array(projectContextSliceSchema).default([]),
+  entities: z.array(projectContextEntitySchema).default([]),
+  relations: z.array(projectContextRelationSchema).default([]),
+  coverage: projectContextCoverageSchema.default(defaultProjectContextCoverage),
+  approvedByUserId: z.string().min(1).optional(),
+  approvedAt: isoDateTimeSchema.optional(),
+  generatedAt: isoDateTimeSchema,
+  supersedesMapId: z.string().min(1).optional(),
+  error: z.string().max(1e3).optional()
+});
+var projectContextRefreshResultSchema = z.object({
+  summary: z.string().trim().min(1).max(4e3),
+  slices: z.array(projectContextSliceSchema).default([]),
+  entities: z.array(projectContextEntitySchema).default([]),
+  relations: z.array(projectContextRelationSchema).default([]),
+  coverage: projectContextCoverageSchema.default(defaultProjectContextCoverage),
+  changedSliceIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  staleSliceIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  verificationPlan: z.array(z.string().trim().min(1).max(300)).min(1),
+  warnings: z.array(z.string().trim().min(1).max(600)).default([])
+});
+var projectContextRefreshItemSchema = baseItemSchema.extend({
+  type: z.literal("projectContextRefresh"),
+  projectId: z.string().min(1),
+  projectContextRefreshId: z.string().min(1),
+  status: projectContextRefreshStatusSchema,
+  source: z.enum(["manual", "runner", "scheduled"]).default("manual"),
+  repositoryLinkId: z.string().min(1).optional(),
+  workItemId: z.string().min(1).optional(),
+  runnerId: z.string().min(1).optional(),
+  previousMapId: z.string().min(1).optional(),
+  proposedMapId: z.string().min(1).optional(),
+  summary: z.string().trim().min(1).max(4e3).optional(),
+  changedSliceIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  staleSliceIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  startedAt: isoDateTimeSchema.optional(),
+  completedAt: isoDateTimeSchema.optional(),
+  failedAt: isoDateTimeSchema.optional(),
+  error: z.string().max(1e3).optional()
+});
+var projectContextPackSchema = z.object({
+  packId: z.string().min(1),
+  accountId: z.string().min(1),
+  projectId: z.string().min(1),
+  workItemId: z.string().min(1).optional(),
+  query: z.string().trim().min(1).max(2e3),
+  mapId: z.string().min(1).optional(),
+  mapVersion: z.number().int().positive().optional(),
+  slices: z.array(projectContextSliceSchema).default([]),
+  entities: z.array(projectContextEntitySchema).default([]),
+  relations: z.array(projectContextRelationSchema).default([]),
+  citations: z.array(assistantCitationSchema).default([]),
+  freshnessWarnings: z.array(z.string().trim().min(1).max(600)).default([]),
+  tokenEstimate: z.number().int().nonnegative().default(0),
+  generatedAt: isoDateTimeSchema
+});
+var contextMissItemSchema = baseItemSchema.extend({
+  type: z.literal("contextMiss"),
+  projectId: z.string().min(1),
+  contextMissId: z.string().min(1),
+  status: contextMissStatusSchema.default("open"),
+  source: z.enum(["runner", "web", "system"]).default("runner"),
+  workItemId: z.string().min(1).optional(),
+  projectContextMapId: z.string().min(1).optional(),
+  query: z.string().trim().min(1).max(2e3),
+  missingSurface: z.string().trim().min(1).max(200),
+  reason: z.string().trim().min(1).max(1200),
+  suggestedPaths: z.array(projectContextRepoPathSchema).default([]),
+  resolvedAt: isoDateTimeSchema.optional(),
+  dismissedAt: isoDateTimeSchema.optional()
+});
 var impactAffectedAreaSchema = z.object({
   name: z.string().trim().min(1),
   description: z.string().trim().min(1).optional()
@@ -825,11 +1099,26 @@ var securityFindingResultSchema = z.object({
   safePaths: z.array(z.string().trim().min(1).max(300)).default([]),
   status: securityFindingStatusSchema.default("open")
 });
+var securityPostureGradeSchema = z.enum(["A", "B", "C", "D", "F", "Unknown"]);
+var securityPostureScanResultGradeSchema = z.preprocess((value) => {
+  if (typeof value !== "string") {
+    return value;
+  }
+  const trimmed = value.trim();
+  if (trimmed.toUpperCase() === "UNKNOWN") {
+    return "Unknown";
+  }
+  const gradeMatch = /^(?:GRADE\s*)?([ABCDF])(?:\s*[+-])?(?:\b|$)/i.exec(trimmed);
+  if (gradeMatch?.[1]) {
+    return gradeMatch[1].toUpperCase();
+  }
+  return "Unknown";
+}, securityPostureGradeSchema);
 var securityPostureScanResultSchema = z.object({
   summary: z.string().trim().min(1).max(2e3),
   baselineVersion: z.string().trim().min(1).max(80),
   postureScore: z.number().min(0).max(100).optional(),
-  postureGrade: z.enum(["A", "B", "C", "D", "F", "Unknown"]).default("Unknown"),
+  postureGrade: securityPostureScanResultGradeSchema.default("Unknown"),
   categorySummaries: z.array(securityCategorySummarySchema).default([]),
   findings: z.array(securityFindingResultSchema).default([]),
   verificationPlan: z.array(z.string().trim().min(1).max(300)).min(1)
@@ -843,6 +1132,7 @@ var securityScanItemSchema = baseItemSchema.extend({
   status: securityScanStatusSchema,
   baselineVersion: z.string().trim().min(1).max(80).default("amistio-security-baseline-v1"),
   workItemId: z.string().min(1).optional(),
+  repositoryLinkId: z.string().min(1).optional(),
   runnerId: z.string().min(1).optional(),
   findingIds: z.array(z.string().min(1)).default([]),
   summary: z.string().trim().min(1).max(2e3).optional(),
@@ -887,13 +1177,82 @@ var securityPostureSnapshotItemSchema = baseItemSchema.extend({
   status: z.enum(["unknown", "fresh", "stale", "running", "failed"]),
   baselineVersion: z.string().trim().min(1).max(80).default("amistio-security-baseline-v1"),
   postureScore: z.number().min(0).max(100).optional(),
-  postureGrade: z.enum(["A", "B", "C", "D", "F", "Unknown"]).default("Unknown"),
+  postureGrade: securityPostureGradeSchema.default("Unknown"),
   severityCounts: securitySeverityCountsSchema.default(defaultSecuritySeverityCounts),
   categorySummaries: z.array(securityCategorySummarySchema).default([]),
   lastScannedAt: isoDateTimeSchema.optional(),
   nextScheduledAt: isoDateTimeSchema.optional(),
   summary: z.string().trim().min(1).max(2e3).optional()
 });
+var appEvaluationFindingResultSchema = z.object({
+  title: z.string().trim().min(1).max(200),
+  category: appEvaluationFindingCategorySchema,
+  severity: appEvaluationFindingSeveritySchema,
+  confidence: appEvaluationFindingConfidenceSchema.default("medium"),
+  summary: z.string().trim().min(1).max(2e3),
+  affectedSurfaces: z.array(z.string().trim().min(1).max(300)).default([]),
+  evidence: z.array(z.string().trim().min(1).max(600)).default([]),
+  suggestedAction: z.string().trim().min(1).max(4e3),
+  verificationPlan: z.array(z.string().trim().min(1).max(300)).min(1),
+  safePaths: z.array(z.string().trim().min(1).max(300)).default([]),
+  proposedLifecycleAction: appEvaluationPlanLifecycleActionSchema.default("none"),
+  relatedArtifactIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  proposedPlanTitle: z.string().trim().min(1).max(200).optional(),
+  proposedPlanRepoPath: z.string().trim().min(1).max(300).optional(),
+  proposedPlanContent: z.string().trim().min(1).max(3e4).optional(),
+  status: appEvaluationFindingStatusSchema.default("open")
+});
+var appEvaluationScanResultSchema = z.object({
+  summary: z.string().trim().min(1).max(2e3),
+  baselineVersion: z.string().trim().min(1).max(80),
+  findings: z.array(appEvaluationFindingResultSchema).default([]),
+  verificationPlan: z.array(z.string().trim().min(1).max(300)).min(1)
+});
+var appEvaluationScanItemSchema = baseItemSchema.extend({
+  type: z.literal("appEvaluationScan"),
+  projectId: z.string().min(1),
+  appEvaluationScanId: z.string().min(1),
+  hourBucket: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:00:00\.000Z$/),
+  source: z.enum(["runner", "manual"]),
+  status: appEvaluationScanStatusSchema,
+  baselineVersion: z.string().trim().min(1).max(80).default("amistio-app-evaluation-v1"),
+  workItemId: z.string().min(1).optional(),
+  repositoryLinkId: z.string().min(1).optional(),
+  runnerId: z.string().min(1).optional(),
+  findingIds: z.array(z.string().min(1)).default([]),
+  summary: z.string().trim().min(1).max(2e3).optional(),
+  startedAt: isoDateTimeSchema.optional(),
+  completedAt: isoDateTimeSchema.optional(),
+  failedAt: isoDateTimeSchema.optional(),
+  error: z.string().max(1e3).optional()
+});
+var appEvaluationFindingItemSchema = baseItemSchema.extend({
+  type: z.literal("appEvaluationFinding"),
+  projectId: z.string().min(1),
+  appEvaluationFindingId: z.string().min(1),
+  appEvaluationScanId: z.string().min(1),
+  title: z.string().trim().min(1).max(200),
+  category: appEvaluationFindingCategorySchema,
+  severity: appEvaluationFindingSeveritySchema,
+  confidence: appEvaluationFindingConfidenceSchema.default("medium"),
+  status: appEvaluationFindingStatusSchema,
+  approvalState: appEvaluationApprovalStateSchema.default("proposed"),
+  summary: z.string().trim().min(1).max(2e3),
+  affectedSurfaces: z.array(z.string().trim().min(1).max(300)).default([]),
+  evidence: z.array(z.string().trim().min(1).max(600)).default([]),
+  safePaths: z.array(z.string().trim().min(1).max(300)).default([]),
+  suggestedAction: z.string().trim().min(1).max(4e3),
+  verificationPlan: z.array(z.string().trim().min(1).max(300)).min(1),
+  proposedLifecycleAction: appEvaluationPlanLifecycleActionSchema.default("none"),
+  relatedArtifactIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  proposedPlanDocumentId: z.string().min(1).optional(),
+  implementationWorkItemId: z.string().min(1).optional(),
+  reviewNotes: z.string().trim().min(1).optional(),
+  reviewedByUserId: z.string().min(1).optional(),
+  reviewedAt: isoDateTimeSchema.optional(),
+  resolvedAt: isoDateTimeSchema.optional(),
+  lastReviewAction: z.enum(["approve", "requestChanges", "dismiss", "acceptRisk", "reopen"]).optional()
+});
 var activityEventItemSchema = baseItemSchema.extend({
   type: z.literal("activityEvent"),
   projectId: z.string().min(1),
@@ -911,6 +1270,11 @@ var activityEventItemSchema = baseItemSchema.extend({
   relatedIssueId: z.string().min(1).optional(),
   relatedSecurityScanId: z.string().min(1).optional(),
   relatedSecurityFindingId: z.string().min(1).optional(),
+  relatedAppEvaluationScanId: z.string().min(1).optional(),
+  relatedAppEvaluationFindingId: z.string().min(1).optional(),
+  relatedProjectContextRefreshId: z.string().min(1).optional(),
+  relatedProjectSystemDiagramId: z.string().min(1).optional(),
+  relatedContextMissId: z.string().min(1).optional(),
   generatedDraftId: z.string().min(1).optional(),
   runnerId: z.string().min(1).optional(),
   repositoryLinkId: z.string().min(1).optional(),
@@ -971,6 +1335,12 @@ var projectItemUnionSchema = z.discriminatedUnion("type", [
   securityScanItemSchema,
   securityFindingItemSchema,
   securityPostureSnapshotItemSchema,
+  appEvaluationScanItemSchema,
+  appEvaluationFindingItemSchema,
+  projectContextMapItemSchema,
+  projectContextRefreshItemSchema,
+  projectSystemDiagramItemSchema,
+  contextMissItemSchema,
   syncCursorItemSchema,
   syncConflictItemSchema,
   workItemSchema,
@@ -1010,16 +1380,43 @@ function isOfficialAmistioApiUrl(value) {
 
 // ../shared/src/brain-documents.ts
 var controlPlaneRoots = /* @__PURE__ */ new Set(["architecture", "context", "decisions", "features", "memory", "plans", "prompts", "workflows"]);
+var documentTypeFolders = {
+  architecture: "architecture",
+  context: "context",
+  decision: "decisions",
+  feature: "features",
+  memory: "memory",
+  plan: "plans",
+  prompt: "prompts",
+  workflow: "workflows"
+};
+var documentTypeByFolder = Object.fromEntries(Object.entries(documentTypeFolders).map(([documentType, folder]) => [folder, documentType]));
 function isControlPlaneTemplateRepoPath(repoPath) {
   const normalized = normalizeRepoPath(repoPath);
   const segments = normalized.split("/").filter(Boolean);
-  const root = segments[0] === "docs" ? segments[1] : segments[0];
+  const root = controlPlaneRootFromSegments(segments);
   const basename = segments[segments.length - 1]?.toLowerCase();
   return Boolean(root && controlPlaneRoots.has(root) && (basename === "_template.md" || basename === "_template.mdx"));
 }
+function documentTypeForBrainRepoPath(repoPath) {
+  const normalized = normalizeRepoPath(repoPath);
+  const segments = normalized.split("/").filter(Boolean);
+  const root = controlPlaneRootFromSegments(segments);
+  return root ? documentTypeByFolder[root] : void 0;
+}
+function inferContentFormatFromRepoPath(repoPath) {
+  if (/\.html?$/i.test(repoPath)) return "html";
+  if (/\.mdx?$/i.test(repoPath)) return "markdown";
+  return void 0;
+}
 function normalizeRepoPath(repoPath) {
   return repoPath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
 }
+function controlPlaneRootFromSegments(segments) {
+  if (segments[0] === "docs" && segments[1] === "html") return segments[2];
+  if (segments[0] === "docs") return segments[1];
+  return segments[0];
+}
 
 // ../shared/src/repo-metadata.ts
 import { z as z2 } from "zod";
@@ -1033,6 +1430,7 @@ var repoLinkMetadataSchema = z2.object({
 var syncedDocumentFrontmatterSchema = z2.object({
   amistioDocumentId: z2.string().min(1),
   amistioDocumentType: z2.string().min(1),
+  amistioContentFormat: z2.enum(["markdown", "html"]).default("markdown"),
   amistioRevision: z2.coerce.number().int().nonnegative(),
   amistioContentHash: z2.string().min(1),
   status: z2.string().optional()
@@ -1183,6 +1581,7 @@ function decideSyncState(state) {
 
 // ../shared/src/next-action.ts
 var nextActionRunnerHeartbeatFreshMs = 15 * 60 * 1e3;
+var nextActionCompletedWorkFreshMs = 60 * 60 * 1e3;
 function computeProjectNextAction(input) {
   const nowMs = input.nowMs ?? Date.now();
   if (!input.projectId) {
@@ -1280,7 +1679,7 @@ function computeProjectNextAction(input) {
   if (!readiness.ready) {
     return runnerWaitAction(readiness, "Runner setup needed");
   }
-  const completedWork = latestWorkItem(input.workItems.filter((item) => item.status === "completed"));
+  const completedWork = latestWorkItem(input.workItems.filter((item) => item.status === "completed" && isFreshCompletedWork(item, nowMs)));
   if (completedWork) {
     return workAction(completedWork, "workCompleted", "none", "success", "Work completed", completedWork.lastStatusMessage ?? "The latest runner work is complete.");
   }
@@ -1374,6 +1773,10 @@ function workAction(workItem, kind, actor, tone, title, message) {
 function latestWorkItem(workItems) {
   return [...workItems].sort((first, second) => Date.parse(second.updatedAt) - Date.parse(first.updatedAt))[0];
 }
+function isFreshCompletedWork(workItem, nowMs) {
+  const timestamp = Date.parse(workItem.lastStatusAt ?? workItem.updatedAt);
+  return timestamp > 0 && nowMs - timestamp <= nextActionCompletedWorkFreshMs;
+}
 function latestTimestamp(values) {
   return values.sort((first, second) => Date.parse(second) - Date.parse(first))[0];
 }
@@ -1715,6 +2118,27 @@ var ApiClient = class {
       { method: "GET" }
     );
   }
+  async listProjectContext(projectId) {
+    return this.request(
+      `/projects/${projectId}/project-context`,
+      z3.object({
+        maps: z3.array(projectContextMapItemSchema),
+        refreshes: z3.array(projectContextRefreshItemSchema),
+        misses: z3.array(contextMissItemSchema),
+        activeMap: projectContextMapItemSchema.optional()
+      }),
+      { method: "GET" }
+    );
+  }
+  async buildProjectContextPack(projectId, query, workItemId) {
+    const params = new URLSearchParams({ packQuery: query });
+    if (workItemId) params.set("workItemId", workItemId);
+    return this.request(
+      `/projects/${projectId}/project-context?${params.toString()}`,
+      projectContextPackSchema,
+      { method: "GET" }
+    );
+  }
   async pushBrainDocuments(projectId, documents) {
     return this.request(
       `/projects/${projectId}/brain-documents`,
@@ -1892,6 +2316,26 @@ var ApiClient = class {
       }
     );
   }
+  async submitAppEvaluationScanResult(projectId, workItemId, result) {
+    return this.request(
+      `/projects/${projectId}/work-items/${workItemId}/app-evaluation-result`,
+      z3.object({ scan: appEvaluationScanItemSchema, findings: z3.array(appEvaluationFindingItemSchema), workItem: workItemSchema }),
+      {
+        method: "POST",
+        body: JSON.stringify(result)
+      }
+    );
+  }
+  async submitProjectContextRefreshResult(projectId, workItemId, result) {
+    return this.request(
+      `/projects/${projectId}/work-items/${workItemId}/project-context-result`,
+      z3.object({ refresh: projectContextRefreshItemSchema, map: projectContextMapItemSchema.optional(), workItem: workItemSchema }),
+      {
+        method: "POST",
+        body: JSON.stringify(result)
+      }
+    );
+  }
   async request(urlPath, schema, init) {
     const response = await fetch(resolveApiUrl(this.options.apiUrl, urlPath), {
       ...init,
@@ -1938,8 +2382,8 @@ var toolSessionMutationSchema = z3.object({
 });
 function resolveApiUrl(apiUrl, urlPath) {
   const base = apiUrl.endsWith("/") ? apiUrl.slice(0, -1) : apiUrl;
-  const path14 = urlPath.startsWith("/") ? urlPath : `/${urlPath}`;
-  return new URL(`${base}${path14}`);
+  const path15 = urlPath.startsWith("/") ? urlPath : `/${urlPath}`;
+  return new URL(`${base}${path15}`);
 }
 
 // src/orchestrator.ts
@@ -2831,6 +3275,15 @@ function currentRunnerMode() {
 function defaultRunnerMetadataDir() {
   return path6.join(os3.homedir(), ".config", "amistio", "runners");
 }
+function updatedCliRunnerLaunchOptions() {
+  return { executablePath: "amistio", directExecutable: true };
+}
+function resolveRunnerDaemonLaunch(input) {
+  if (input.directExecutable) {
+    return { executablePath: input.executablePath ?? "amistio", args: input.args };
+  }
+  return { executablePath: input.executablePath ?? process.execPath, args: [input.scriptPath ?? process.argv[1], ...input.args] };
+}
 async function startRunnerDaemon(input) {
   const metadataDir = input.metadataDir ?? defaultRunnerMetadataDir();
   const existing = await readRunnerDaemonMetadata(input, metadataDir);
@@ -2840,7 +3293,12 @@ async function startRunnerDaemon(input) {
   await mkdir5(metadataDir, { recursive: true });
   const logPath = path6.join(metadataDir, `${runnerDaemonKey(input)}.log`);
   const logFd = openSync(logPath, "a");
-  const child = spawn2(input.executablePath ?? process.execPath, [input.scriptPath ?? process.argv[1], ...input.args], {
+  const launch = resolveRunnerDaemonLaunch({
+    args: input.args,
+    ...input.executablePath ? { executablePath: input.executablePath } : {},
+    ...input.scriptPath ? { scriptPath: input.scriptPath } : {}
+  });
+  const child = spawn2(launch.executablePath, launch.args, {
     cwd: input.rootDir,
     detached: true,
     env: {
@@ -2877,7 +3335,13 @@ async function restartRunnerDaemonProcess(metadata, args, input = {}) {
   await mkdir5(metadataDir, { recursive: true });
   const logPath = metadata.logPath ?? path6.join(metadataDir, `${runnerDaemonKey(metadata)}.log`);
   const logFd = openSync(logPath, "a");
-  const child = spawn2(input.executablePath ?? process.execPath, [input.scriptPath ?? process.argv[1], ...args], {
+  const launch = resolveRunnerDaemonLaunch({
+    args,
+    ...input.executablePath ? { executablePath: input.executablePath } : {},
+    ...input.scriptPath ? { scriptPath: input.scriptPath } : {},
+    ...input.directExecutable ? { directExecutable: true } : {}
+  });
+  const child = spawn2(launch.executablePath, launch.args, {
     cwd: metadata.rootDir,
     detached: true,
     env: {
@@ -3356,6 +3820,7 @@ import { promisify as promisify3 } from "node:util";
 var execFileAsync3 = promisify3(execFile3);
 var legacySyncRoots = ["architecture", "context", "decisions", "features", "memory", "plans", "prompts", "workflows"];
 var syncRoots = legacySyncRoots.map((syncRoot) => `docs/${syncRoot}`);
+var htmlSyncRoot = "docs/html";
 var documentTypeByRoot = {
   architecture: "architecture",
   context: "context",
@@ -3443,15 +3908,15 @@ async function collectSyncStatus(rootDir, webDocuments = []) {
   return { status, items, counts };
 }
 async function readLocalSyncedDocuments(rootDir) {
-  const markdownFiles = await findMarkdownFiles(rootDir);
+  const documentFiles = await findBrainDocumentFiles(rootDir);
   const documents = [];
-  for (const fullPath of markdownFiles) {
+  for (const fullPath of documentFiles) {
     const raw = await readFile6(fullPath, "utf8");
-    const parsed = parseSyncedMarkdown(raw);
+    const repoPath = toRepoPath(rootDir, fullPath);
+    const parsed = parseSyncedDocument(raw, repoPath);
     if (!parsed) {
       continue;
     }
-    const repoPath = toRepoPath(rootDir, fullPath);
     if (isControlPlaneTemplateRepoPath(repoPath)) {
       continue;
     }
@@ -3497,7 +3962,7 @@ async function materializeBrainDocuments(rootDir, documents, options = {}) {
       continue;
     }
     await mkdir7(path8.dirname(fullPath), { recursive: true });
-    await writeFile7(fullPath, createSyncedDocumentMarkdown(document), "utf8");
+    await writeFile7(fullPath, createSyncedDocumentContent(document), "utf8");
     result.written.push(document.repoPath);
   }
   return result;
@@ -3515,6 +3980,7 @@ async function collectDirtyDocumentsForPush(rootDir, metadata) {
       projectId: metadata.amistioProjectId,
       documentId: document.frontmatter.amistioDocumentId,
       documentType,
+      contentFormat: document.frontmatter.amistioContentFormat,
       title: inferTitle(document.content, document.repoPath),
       status: "reviewing",
       repoPath: document.repoPath,
@@ -3552,11 +4018,15 @@ function autoSyncSkipCounts(skipped) {
     unreadable: skipped.filter((item) => item.reason === "unreadable").length
   };
 }
-function createSyncedDocumentMarkdown(document) {
+function createSyncedDocumentContent(document) {
+  return (document.contentFormat ?? inferContentFormatFromRepoPath(document.repoPath) ?? "markdown") === "html" ? createSyncedDocumentHtml(document) : createSyncedDocumentMarkdownContent(document);
+}
+function createSyncedDocumentMarkdownContent(document) {
   return [
     "---",
     `amistioDocumentId: ${document.documentId}`,
     `amistioDocumentType: ${document.documentType}`,
+    `amistioContentFormat: ${document.contentFormat ?? "markdown"}`,
     `amistioRevision: ${document.revision}`,
     `amistioContentHash: ${document.contentHash}`,
     `status: ${document.status}`,
@@ -3565,6 +4035,24 @@ function createSyncedDocumentMarkdown(document) {
     ""
   ].join("\n");
 }
+function createSyncedDocumentHtml(document) {
+  return [
+    "<!--",
+    `amistioDocumentId: ${document.documentId}`,
+    `amistioDocumentType: ${document.documentType}`,
+    "amistioContentFormat: html",
+    `amistioRevision: ${document.revision}`,
+    `amistioContentHash: ${document.contentHash}`,
+    `status: ${document.status}`,
+    "-->",
+    document.content,
+    ""
+  ].join("\n");
+}
+function parseSyncedDocument(content, repoPath) {
+  const format = inferContentFormatFromRepoPath(repoPath);
+  return format === "html" ? parseSyncedHtml(content) : parseSyncedMarkdown(content);
+}
 function parseSyncedMarkdown(content) {
   const rawFrontmatter = parseFrontmatter(content);
   const frontmatter = syncedDocumentFrontmatterSchema.safeParse(rawFrontmatter);
@@ -3579,10 +4067,32 @@ function parseSyncedMarkdown(content) {
   const bodyStart = closingLineEnd === -1 ? content.length : closingLineEnd + 1;
   return { frontmatter: frontmatter.data, content: content.slice(bodyStart).replace(/\n$/, "") };
 }
+function parseSyncedHtml(content) {
+  const trimmedStart = content.trimStart();
+  if (!trimmedStart.startsWith("<!--")) {
+    return void 0;
+  }
+  const startOffset = content.indexOf("<!--");
+  const closingMarker = content.indexOf("-->", startOffset + 4);
+  if (closingMarker === -1) {
+    return void 0;
+  }
+  const metadataLines = content.slice(startOffset + 4, closingMarker).split(/\r?\n/);
+  const metadata = Object.fromEntries(metadataLines.map((line) => {
+    const separator = line.indexOf(":");
+    return separator === -1 ? void 0 : [line.slice(0, separator).trim(), line.slice(separator + 1).trim()];
+  }).filter((entry) => Boolean(entry?.[0])));
+  const frontmatter = syncedDocumentFrontmatterSchema.safeParse({ ...metadata, amistioContentFormat: "html" });
+  if (!frontmatter.success) {
+    return void 0;
+  }
+  const bodyStart = content.indexOf("\n", closingMarker + 3);
+  return { frontmatter: frontmatter.data, content: content.slice(bodyStart === -1 ? closingMarker + 3 : bodyStart + 1).replace(/\n$/, "") };
+}
 async function readExistingSyncedDocument(fullPath) {
   try {
     const raw = await readFile6(fullPath, "utf8");
-    const parsed = parseSyncedMarkdown(raw);
+    const parsed = parseSyncedDocument(raw, fullPath);
     if (!parsed) {
       return { exists: true };
     }
@@ -3603,23 +4113,23 @@ async function readExistingSyncedDocument(fullPath) {
     throw error;
   }
 }
-async function findMarkdownFiles(rootDir) {
+async function findBrainDocumentFiles(rootDir) {
   const files = [];
-  for (const syncRoot of syncRoots) {
+  for (const syncRoot of [...syncRoots, htmlSyncRoot]) {
     const fullRoot = path8.join(rootDir, syncRoot);
     if (!await exists2(fullRoot)) {
       continue;
     }
-    await walkMarkdownFiles(fullRoot, files);
+    await walkBrainDocumentFiles(fullRoot, files);
   }
   return files;
 }
-async function walkMarkdownFiles(directory, files) {
+async function walkBrainDocumentFiles(directory, files) {
   for (const entry of await readdir3(directory, { withFileTypes: true })) {
     const fullPath = path8.join(directory, entry.name);
     if (entry.isDirectory()) {
-      await walkMarkdownFiles(fullPath, files);
-    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      await walkBrainDocumentFiles(fullPath, files);
+    } else if (entry.isFile() && /\.(md|mdx|html?)$/i.test(entry.name)) {
       files.push(fullPath);
     }
   }
@@ -3641,7 +4151,7 @@ function safeRepoPath(rootDir, repoPath) {
 }
 function isControlPlanePath(repoPath) {
   const normalized = path8.normalize(repoPath);
-  return syncRoots.some((syncRoot) => normalized === syncRoot || normalized.startsWith(`${syncRoot}${path8.sep}`));
+  return syncRoots.some((syncRoot) => normalized === syncRoot || normalized.startsWith(`${syncRoot}${path8.sep}`)) || normalized === htmlSyncRoot || normalized.startsWith(`${htmlSyncRoot}${path8.sep}`);
 }
 function canonicalControlPlaneRepoPath(repoPath) {
   const normalized = repoPath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
@@ -3656,7 +4166,9 @@ function toRepoPath(rootDir, fullPath) {
 }
 function inferTitle(content, repoPath) {
   const heading = content.split("\n").find((line) => line.startsWith("# "))?.replace(/^#\s+/, "").trim();
-  return heading || path8.basename(repoPath, path8.extname(repoPath));
+  if (heading) return heading;
+  const htmlHeading = content.match(/<h1\b[^>]*>([\s\S]*?)<\/h1>/i)?.[1]?.replace(/<[^>]+>/g, "").trim();
+  return htmlHeading || path8.basename(repoPath, path8.extname(repoPath));
 }
 async function collectExternalBrainDocumentsForPush(rootDir, metadata, existingDocuments, options) {
   const root = path8.resolve(rootDir);
@@ -3689,7 +4201,7 @@ async function collectExternalBrainDocumentsForPush(rootDir, metadata, existingD
       skipped.push({ repoPath: normalizedRepoPath, reason: "unreadable" });
       continue;
     }
-    if (parseSyncedMarkdown(content)) {
+    if (parseSyncedDocument(content, normalizedRepoPath)) {
       skipped.push({ repoPath: normalizedRepoPath, reason: "alreadyManaged" });
       continue;
     }
@@ -3719,6 +4231,7 @@ async function collectExternalBrainDocumentsForPush(rootDir, metadata, existingD
       projectId: metadata.amistioProjectId,
       documentId,
       documentType,
+      contentFormat: inferContentFormatFromRepoPath(canonicalRepoPath) ?? "markdown",
       title: inferTitle(content, canonicalRepoPath),
       status: "reviewing",
       repoPath: canonicalRepoPath,
@@ -3747,7 +4260,7 @@ async function listAutoSyncCandidatePaths(rootDir) {
     return uniqueSortedRepoPaths(gitFiles.split("\n").map(normalizeRepoPath3).filter((repoPath) => repoPath && isRecognizedBrainRepoPath(repoPath)));
   }
   const files = [];
-  for (const syncRoot of [...syncRoots, ...legacySyncRoots]) {
+  for (const syncRoot of [...syncRoots, htmlSyncRoot, ...legacySyncRoots]) {
     const fullRoot = path8.join(rootDir, syncRoot);
     if (await exists2(fullRoot)) {
       await walkAutoSyncFiles(rootDir, fullRoot, files);
@@ -3771,7 +4284,7 @@ async function walkAutoSyncFiles(rootDir, directory, files) {
 function autoSyncPathSkipReason(repoPath) {
   if (autoSyncMetadataPaths.has(repoPath)) return "metadata";
   if (isControlPlaneTemplateRepoPath(repoPath)) return "template";
-  if (!/\.(md|mdx)$/i.test(repoPath)) return "unsupported";
+  if (!/\.(md|mdx|html?)$/i.test(repoPath)) return "unsupported";
   const basename = repoPath.split("/").at(-1)?.toLowerCase() ?? "";
   if (basename.startsWith(".") || basename.endsWith(".lock") || basename.includes(".env") || basename.includes("secret") || basename.includes("credential")) return "excluded";
   if (repoPath.split("/").some((segment) => autoSyncExcludedDirectoryNames.has(segment) || autoSyncGeneratedPathSegments.has(segment))) return "excluded";
@@ -3779,10 +4292,13 @@ function autoSyncPathSkipReason(repoPath) {
 }
 function isRecognizedBrainRepoPath(repoPath) {
   const normalized = normalizeRepoPath3(repoPath);
-  const [firstSegment, secondSegment] = normalized.split("/");
-  return Boolean(firstSegment === "docs" && secondSegment && legacySyncRoots.includes(secondSegment) || firstSegment && legacySyncRoots.includes(firstSegment));
+  const [firstSegment, secondSegment, thirdSegment] = normalized.split("/");
+  return Boolean(firstSegment === "docs" && secondSegment === "html" && thirdSegment && legacySyncRoots.includes(thirdSegment) || firstSegment === "docs" && secondSegment && legacySyncRoots.includes(secondSegment) || firstSegment && legacySyncRoots.includes(firstSegment));
 }
 function documentTypeForRepoPath(repoPath) {
+  return documentTypeForBrainRepoPath(repoPath) ?? legacyDocumentTypeForRepoPath(repoPath);
+}
+function legacyDocumentTypeForRepoPath(repoPath) {
   const normalized = normalizeRepoPath3(repoPath);
   const segments = normalized.split("/");
   const root = segments[0] === "docs" ? segments[1] : segments[0];
@@ -3801,6 +4317,7 @@ function parseFrontmatterFromSyncedDocument(frontmatter) {
   return {
     amistioDocumentId: frontmatter.amistioDocumentId,
     amistioDocumentType: frontmatter.amistioDocumentType,
+    amistioContentFormat: frontmatter.amistioContentFormat,
     amistioRevision: frontmatter.amistioRevision,
     amistioContentHash: frontmatter.amistioContentHash,
     ...frontmatter.status ? { status: frontmatter.status } : {}
@@ -3864,6 +4381,10 @@ var issueDiagnosisStart = "AMISTIO_ISSUE_DIAGNOSIS_START";
 var issueDiagnosisEnd = "AMISTIO_ISSUE_DIAGNOSIS_END";
 var securityPostureStart = "AMISTIO_SECURITY_POSTURE_START";
 var securityPostureEnd = "AMISTIO_SECURITY_POSTURE_END";
+var appEvaluationStart = "AMISTIO_APP_EVALUATION_START";
+var appEvaluationEnd = "AMISTIO_APP_EVALUATION_END";
+var projectContextRefreshStart = "AMISTIO_PROJECT_CONTEXT_REFRESH_START";
+var projectContextRefreshEnd = "AMISTIO_PROJECT_CONTEXT_REFRESH_END";
 function createWorkExecutionPrompt(workItem, context) {
   if (workItem.workKind === "brainGeneration") {
     return createBrainGenerationPrompt(workItem);
@@ -3883,6 +4404,12 @@ function createWorkExecutionPrompt(workItem, context) {
   if (workItem.workKind === "securityPostureScan") {
     return createSecurityPostureScanPrompt(workItem, context?.securityPostureScan);
   }
+  if (workItem.workKind === "appEvaluationScan") {
+    return createAppEvaluationScanPrompt(workItem, context?.appEvaluationScan);
+  }
+  if (workItem.workKind === "projectContextRefresh") {
+    return createProjectContextRefreshPrompt(workItem, context?.projectContextRefresh);
+  }
   return [
     "# Amistio Work Execution",
     "",
@@ -3911,6 +4438,77 @@ function createWorkExecutionPrompt(workItem, context) {
     "- Run relevant verification commands when feasible and summarize results."
   ].join("\n");
 }
+function createProjectContextRefreshPrompt(workItem, context) {
+  const approvedContext = (context?.documents ?? []).filter((document) => document.status === "approved" || document.syncState === "approved" || document.syncState === "synced").slice(0, 24).map((document) => [
+    `### ${document.title}`,
+    `documentId: ${document.documentId}`,
+    `documentType: ${document.documentType}`,
+    `repoPath: ${document.repoPath}`,
+    `revision: ${document.revision}`,
+    document.content.slice(0, 3e3)
+  ].join("\n")).join("\n\n");
+  const activeMap = context?.activeMap;
+  const previousMap = activeMap ? [
+    `Map ID: ${activeMap.projectContextMapId}`,
+    `Version: ${activeMap.version}`,
+    `Status: ${activeMap.status}`,
+    `Coverage: ${activeMap.coverage.status}`,
+    `Summary: ${activeMap.summary}`,
+    "Slices:",
+    ...activeMap.slices.slice(0, 20).map((slice) => `- ${slice.sliceId} / ${slice.kind} / ${slice.freshness}: ${slice.title} - ${slice.summary.slice(0, 500)}`)
+  ].join("\n") : "No approved project context map was loaded. Build the initial map.";
+  return [
+    "# Amistio Living Project Context Refresh",
+    "",
+    "You are running locally through the Amistio CLI inside the user's repository.",
+    "Run a read-only project context refresh that captures the whole app as bounded, reviewable knowledge.",
+    "Do not modify files, create branches, commit, install packages, run implementation prompts, call external services, or make unaudited network calls.",
+    "Use only safe local inspection and focused diagnostic commands that do not expose secrets.",
+    "",
+    "## Work Item",
+    "",
+    `Title: ${workItem.title}`,
+    `Work item ID: ${workItem.workItemId}`,
+    `Project ID: ${workItem.projectId}`,
+    `Project context refresh ID: ${workItem.projectContextRefreshId ?? "unknown"}`,
+    "",
+    "## Refresh Request",
+    "",
+    workItem.sourceWish ?? "Refresh the living project context map.",
+    "",
+    "## Approved Project Brain Context",
+    "",
+    approvedContext || "No approved project-brain records were loaded. Inspect local repository files as needed and explain the gap in the coverage warnings.",
+    "",
+    "## Previous Context Map",
+    "",
+    previousMap,
+    "",
+    "## Mapping Requirements",
+    "",
+    "- Create slices for architecture, domain, data, API, frontend, backend, CLI, workflows, operations, security, and testing when those surfaces exist.",
+    "- Capture entities and relations that explain how the app is put together and where future work should look first.",
+    "- Prefer summaries, repository-relative paths, short citations, tags, and freshness status over raw source excerpts.",
+    "- Mark stale or missing areas explicitly instead of guessing.",
+    "- Keep repoPaths repository-relative; never include /absolute paths or ../ traversal.",
+    "",
+    "## Data Safety",
+    "",
+    "- Persist summaries, entities, relations, citations, and repository-relative paths only.",
+    "- Do not include raw source dumps, secrets, env vars, process lists, absolute local paths, credential values, tokens, provider sessions, or destructive shell output.",
+    "- Citation excerpts must be short evidence snippets, not code payloads.",
+    "",
+    "## Output Contract",
+    "",
+    "Print exactly one JSON object between the markers below. The CLI will submit only this structured refresh result back to Amistio.",
+    "",
+    projectContextRefreshStart,
+    '{"summary":"The app uses docs/ as the orchestration control plane and a local runner for source-aware work.","slices":[{"sliceId":"slice_control_plane","kind":"architecture","title":"Docs control plane","summary":"ADRs, plans, prompts, context, and memory under docs/ guide implementation work.","repoPaths":["AGENTS.md","docs/architecture/overview.md"],"tags":["orchestrator","docs"],"citations":[{"source":"localSource","repoPath":"AGENTS.md","excerpt":"docs/ control-plane folders are the source of truth."}],"freshness":"fresh","confidence":0.9}],"entities":[{"entityId":"entity_local_runner","name":"Local runner","entityType":"component","summary":"Executes approved work locally and returns redacted structured results.","sliceIds":["slice_control_plane"],"confidence":0.8}],"relations":[{"relationId":"rel_runner_uses_docs","relationType":"uses","fromId":"entity_local_runner","toId":"slice_control_plane","summary":"The runner reads approved docs context before executing work.","confidence":0.8}],"coverage":{"status":"partial","sliceCount":1,"staleSliceCount":0,"missingAreas":["runtime data flow"],"warnings":[]},"changedSliceIds":["slice_control_plane"],"staleSliceIds":[],"verificationPlan":["Review the proposed context map in Amistio","Run focused checks for any stale areas"]}',
+    projectContextRefreshEnd,
+    "",
+    "Do not put Markdown fences around the markers. Do not implement any changes."
+  ].join("\n");
+}
 function createSecurityPostureScanPrompt(workItem, context) {
   const approvedContext = (context?.documents ?? []).filter((document) => document.status === "approved" || document.syncState === "approved" || document.syncState === "synced").slice(0, 20).map((document) => [
     `### ${document.title}`,
@@ -3968,6 +4566,63 @@ function createSecurityPostureScanPrompt(workItem, context) {
     "Do not put Markdown fences around the markers. Do not implement remediation."
   ].join("\n");
 }
+function createAppEvaluationScanPrompt(workItem, context) {
+  const approvedContext = (context?.documents ?? []).filter((document) => document.status === "approved" || document.syncState === "approved" || document.syncState === "synced").slice(0, 24).map((document) => [
+    `### ${document.title}`,
+    `documentId: ${document.documentId}`,
+    `documentType: ${document.documentType}`,
+    `repoPath: ${document.repoPath}`,
+    `revision: ${document.revision}`,
+    document.content.slice(0, 3e3)
+  ].join("\n")).join("\n\n");
+  return [
+    "# Amistio App Evaluation Scan",
+    "",
+    "You are running locally through the Amistio CLI inside the user's repository.",
+    "Run a read-only app evaluation scan and produce approval-gated improvement and cleanup findings.",
+    "Do not modify files, create branches, commit, install packages, run implementation prompts, delete or archive plans, call external services, or make unaudited network calls.",
+    "Use only safe local inspection and focused diagnostic commands that do not expose secrets.",
+    "",
+    "## Work Item",
+    "",
+    `Title: ${workItem.title}`,
+    `Work item ID: ${workItem.workItemId}`,
+    `Project ID: ${workItem.projectId}`,
+    `App evaluation scan ID: ${workItem.appEvaluationScanId ?? "unknown"}`,
+    "",
+    "## Scan Request",
+    "",
+    workItem.sourceWish ?? "Run the Amistio app evaluation baseline.",
+    "",
+    "## Approved Project Brain Context",
+    "",
+    approvedContext || "No approved project-brain records were loaded. Inspect local repository files as needed and explain the gap in the summary.",
+    "",
+    "## Baseline Requirements",
+    "",
+    "- Check app verification health: lint, typecheck, test, build, CI references, flaky or missing gates.",
+    "- Check product and docs drift between approved context, plans, prompts, and current implementation.",
+    "- Check old plans and prompts for cleanup candidates, but only propose lifecycle actions such as markCompleted, markSuperseded, archive, keepActive, or none.",
+    "- Check missing memory or workflow updates when repeated lessons or operational rules are visible.",
+    "- Check release readiness, UX, accessibility, performance, reliability, and security-posture follow-through at a summary level.",
+    "",
+    "## Data Safety",
+    "",
+    "- Persist summaries, recommended actions, repository-relative paths, and redacted evidence only.",
+    "- Do not include raw source dumps, secrets, env vars, process lists, absolute local paths, credential values, tokens, provider sessions, or destructive shell output.",
+    "- Use safePaths for repo-relative paths only; never include /absolute paths or ../ traversal.",
+    "",
+    "## Output Contract",
+    "",
+    "Print exactly one JSON object between the markers below. The CLI will submit only this structured scan result back to Amistio.",
+    "",
+    appEvaluationStart,
+    '{"summary":"The app is generally healthy, but one release-readiness plan needs cleanup and verification evidence should be refreshed.","baselineVersion":"amistio-app-evaluation-v1","findings":[{"title":"Stale release plan should be marked superseded","category":"planCleanup","severity":"low","confidence":"high","summary":"A release plan appears to describe a workflow that has since been replaced by a newer accepted plan.","affectedSurfaces":["docs/plans"],"evidence":["A newer plan references the same scope and status, while the older plan remains proposed."],"suggestedAction":"Prepare a cleanup update that marks the stale plan superseded and links to the newer plan.","verificationPlan":["Review both plan files","Confirm the newer plan is accepted before changing lifecycle state"],"safePaths":["docs/plans/PLAN-example.md"],"proposedLifecycleAction":"markSuperseded","relatedArtifactIds":[]}],"verificationPlan":["Review App Evaluation findings for approval","Run the canonical verify gate before implementing approved actions"]}',
+    appEvaluationEnd,
+    "",
+    "Do not put Markdown fences around the markers. Do not implement improvements or cleanup."
+  ].join("\n");
+}
 function createIssueDiagnosisPrompt(workItem, context) {
   const issue = context?.issue;
   const approvedContext = (context?.documents ?? []).filter((document) => document.status === "approved" || document.syncState === "approved" || document.syncState === "synced").slice(0, 16).map((document) => [
@@ -4018,11 +4673,69 @@ function createIssueDiagnosisPrompt(workItem, context) {
     "Do not put Markdown fences around the markers. Do not implement the fix."
   ].join("\n");
 }
-function createImpactPreviewPrompt(workItem, context) {
-  const implementationPrompt = context?.implementationPrompt;
-  const approvedContext = (context?.documents ?? []).filter((document) => document.status === "approved" || document.syncState === "approved" || document.syncState === "synced").slice(0, 16).map((document) => [
-    `### ${document.title}`,
-    `documentId: ${document.documentId}`,
+function formatProjectContextMap(map, query, contextPack) {
+  if ((!map || map.status !== "approved") && !contextPack) {
+    return "No approved living context map was loaded. Use approved brain records and inspect local source only where needed.";
+  }
+  if (!map || map.status !== "approved") {
+    return [
+      `Context pack ID: ${contextPack?.packId ?? "unknown"}`,
+      contextPack?.freshnessWarnings.length ? `Freshness warnings: ${contextPack.freshnessWarnings.join(" | ")}` : "Freshness warnings: none recorded",
+      "No approved living context map was loaded. Use approved brain records and inspect local source only where needed."
+    ].join("\n");
+  }
+  const tokens2 = tokenizeForContext(query);
+  const candidateSlices = contextPack?.slices.length ? contextPack.slices : map.slices;
+  const rankedSlices = [...candidateSlices].map((slice) => ({ slice, score: scoreContextSlice(tokens2, slice.title, slice.summary, [...slice.repoPaths, ...slice.tags, ...slice.ownerHints].join(" ")) })).sort((first, second) => second.score - first.score || first.slice.title.localeCompare(second.slice.title));
+  const selectedSlices = rankedSlices.filter((entry) => entry.score > 0).map((entry) => entry.slice).slice(0, 8);
+  const slices = (selectedSlices.length ? selectedSlices : candidateSlices.slice(0, 8)).map((slice) => [
+    `### ${slice.title}`,
+    `sliceId: ${slice.sliceId}`,
+    `kind: ${slice.kind}`,
+    `freshness: ${slice.freshness}`,
+    `confidence: ${Math.round(slice.confidence * 100)}%`,
+    slice.repoPaths.length ? `repoPaths: ${slice.repoPaths.slice(0, 12).join(", ")}` : "repoPaths: none recorded",
+    slice.summary
+  ].join("\n")).join("\n\n");
+  const entities = (contextPack?.entities.length ? contextPack.entities : map.entities).slice(0, 12).map((entity) => `- ${entity.name} (${entity.entityType}): ${entity.summary ?? entity.entityId}`).join("\n");
+  const relations = (contextPack?.relations.length ? contextPack.relations : map.relations).slice(0, 12).map((relation) => `- ${relation.fromId} ${relation.relationType} ${relation.toId}: ${relation.summary}`).join("\n");
+  return [
+    contextPack ? `Context pack ID: ${contextPack.packId}` : "Context pack ID: not recorded",
+    `Map ID: ${map.projectContextMapId}`,
+    `Version: ${map.version}`,
+    contextPack?.tokenEstimate !== void 0 ? `Pack token estimate: ${contextPack.tokenEstimate}` : "Pack token estimate: not recorded",
+    `Coverage: ${map.coverage.status}; slices ${map.coverage.sliceCount}; stale ${map.coverage.staleSliceCount}`,
+    contextPack?.freshnessWarnings.length ? `Freshness warnings: ${contextPack.freshnessWarnings.join(" | ")}` : "Freshness warnings: none recorded",
+    map.coverage.missingAreas.length ? `Missing areas: ${map.coverage.missingAreas.join(", ")}` : "Missing areas: none recorded",
+    map.coverage.warnings.length ? `Warnings: ${map.coverage.warnings.join(" | ")}` : "Warnings: none recorded",
+    "",
+    map.summary,
+    "",
+    "### Relevant Context Slices",
+    slices || "No slices recorded.",
+    "",
+    "### Entities",
+    entities || "No entities recorded.",
+    "",
+    "### Relations",
+    relations || "No relations recorded."
+  ].join("\n");
+}
+function tokenizeForContext(value) {
+  return [...new Set(value.toLowerCase().match(/[a-z0-9][a-z0-9_-]{2,}/g) ?? [])].slice(0, 24);
+}
+function scoreContextSlice(tokens2, title, summary, metadata) {
+  const haystackTitle = title.toLowerCase();
+  const haystackSummary = summary.toLowerCase();
+  const haystackMetadata = metadata.toLowerCase();
+  return tokens2.reduce((score, token) => score + (haystackTitle.includes(token) ? 5 : 0) + (haystackMetadata.includes(token) ? 3 : 0) + (haystackSummary.includes(token) ? 1 : 0), 0);
+}
+function createImpactPreviewPrompt(workItem, context) {
+  const implementationPrompt = context?.implementationPrompt;
+  const livingContext = formatProjectContextMap(context?.activeMap, workItem.sourceWish ?? workItem.title, context?.contextPack);
+  const approvedContext = (context?.documents ?? []).filter((document) => document.status === "approved" || document.syncState === "approved" || document.syncState === "synced").slice(0, 16).map((document) => [
+    `### ${document.title}`,
+    `documentId: ${document.documentId}`,
     `documentType: ${document.documentType}`,
     `repoPath: ${document.repoPath}`,
     `revision: ${document.revision}`,
@@ -4048,6 +4761,10 @@ function createImpactPreviewPrompt(workItem, context) {
     "",
     implementationPrompt ? implementationPrompt.content : workItem.sourceWish ?? workItem.title,
     "",
+    "## Approved Living Project Context Map",
+    "",
+    livingContext,
+    "",
     "## Approved Project Brain Context",
     "",
     approvedContext || "No approved project-brain records were loaded. Inspect the local repository and explain the gap in the report.",
@@ -4073,6 +4790,7 @@ function createImpactPreviewPrompt(workItem, context) {
 }
 function createAssistantQuestionPrompt(workItem, context) {
   const question = context?.question.content ?? workItem.sourceWish ?? workItem.title;
+  const livingContext = formatProjectContextMap(context?.activeMap, question, context?.contextPack);
   const priorMessages = (context?.messages ?? []).filter((message) => message.messageId !== context?.question.messageId).slice(-12).map((message) => `- ${message.role} / ${message.status}: ${message.content}`).join("\n");
   const brainContext = (context?.documents ?? []).filter((document) => document.status === "approved" || document.syncState === "approved" || document.syncState === "synced").slice(0, 12).map((document) => [
     `### ${document.title}`,
@@ -4099,6 +4817,10 @@ function createAssistantQuestionPrompt(workItem, context) {
     `Project ID: ${workItem.projectId}`,
     `Assistant message ID: ${workItem.assistantMessageId ?? context?.question.messageId ?? "unknown"}`,
     "",
+    "## Approved Living Project Context Map",
+    "",
+    livingContext,
+    "",
     "## Approved Project Brain Context",
     "",
     brainContext || "No approved project-brain records were loaded. Say what you inspected locally and avoid pretending citations exist.",
@@ -4112,6 +4834,7 @@ function createAssistantQuestionPrompt(workItem, context) {
     "- Keep repository source, secrets, tokens, local credential paths, and provider session references local.",
     "- Summarize findings instead of dumping source code. Tiny identifiers, filenames, and short excerpts are acceptable when necessary.",
     '- Use sourceBoundary "projectBrain" when the answer only uses project-brain records.',
+    "- Treat the approved living context map as project-brain context; use it to avoid broad repository rereads when it is fresh and relevant.",
     '- Use sourceBoundary "localSource" when you inspected local repository files.',
     '- Use sourceBoundary "mixed" when both project-brain records and local files shaped the answer.',
     "- Include citations for project-brain records with documentId/title/repoPath where relevant.",
@@ -4214,8 +4937,35 @@ function parseSecurityPostureScanResult(output) {
   const parsed = JSON.parse(stripJsonFence(payload));
   return securityPostureScanResultSchema.parse(parsed);
 }
+function parseAppEvaluationScanResult(output) {
+  const start = output.indexOf(appEvaluationStart);
+  const end = output.indexOf(appEvaluationEnd, start + appEvaluationStart.length);
+  if (start === -1 || end === -1 || end <= start) {
+    throw new Error("Local AI scan did not return an Amistio app evaluation block.");
+  }
+  const payload = output.slice(start + appEvaluationStart.length, end).trim();
+  const parsed = JSON.parse(stripJsonFence(payload));
+  return appEvaluationScanResultSchema.parse(parsed);
+}
+function parseProjectContextRefreshResult(output) {
+  const start = output.indexOf(projectContextRefreshStart);
+  const end = output.indexOf(projectContextRefreshEnd, start + projectContextRefreshStart.length);
+  if (start === -1 || end === -1 || end <= start) {
+    throw new Error("Local AI refresh did not return an Amistio project context block.");
+  }
+  const payload = output.slice(start + projectContextRefreshStart.length, end).trim();
+  const parsed = JSON.parse(stripJsonFence(payload));
+  return projectContextRefreshResultSchema.parse(parsed);
+}
+function projectContextRefreshSubmissionFailureSummary(result) {
+  if (result.refresh.status !== "failed" && result.workItem.status !== "failed") {
+    return void 0;
+  }
+  return result.refresh.error ?? result.workItem.lastStatusMessage ?? "Server rejected the project context refresh result.";
+}
 function createBrainGenerationPrompt(workItem) {
   const wish = workItem.sourceWish ?? workItem.title;
+  const artifactFormatPreference = workItem.artifactFormatPreference ?? "markdown";
   return [
     "# Amistio Brain Generation",
     "",
@@ -4232,6 +4982,7 @@ function createBrainGenerationPrompt(workItem) {
     `Work item ID: ${workItem.workItemId}`,
     `Project ID: ${workItem.projectId}`,
     `Generated draft ID: ${workItem.generatedDraftId ?? "unknown"}`,
+    `Artifact format preference: ${artifactFormatPreference}`,
     "",
     "## Read First",
     "",
@@ -4241,7 +4992,7 @@ function createBrainGenerationPrompt(workItem) {
     "",
     "## Generate Artifacts",
     "",
-    "Return Markdown artifacts that should enter human review before implementation. Use only these document types and matching repo roots:",
+    "Return artifacts that should enter human review before implementation. Use only these document types and matching repo roots:",
     "",
     "- architecture -> docs/architecture/",
     "- context -> docs/context/",
@@ -4251,20 +5002,35 @@ function createBrainGenerationPrompt(workItem) {
     "- plan -> docs/plans/",
     "- prompt -> docs/prompts/",
     "- workflow -> docs/workflows/",
+    "- HTML companions -> docs/html/<same-folder>/ using .html, for example docs/html/plans/PLAN-example.html",
+    "",
+    artifactFormatPreferenceInstructions(artifactFormatPreference),
     "",
-    "Each artifact needs documentType, title, repoPath, and content. Include at least a plan and an implementation prompt when implementation work is implied. Use model-agnostic prompt wording.",
+    "Each artifact needs documentType, contentFormat, title, repoPath, and content. contentFormat may be omitted only for Markdown. Include at least a plan and an implementation prompt when implementation work is implied. Use model-agnostic prompt wording.",
     "",
     "## Output Contract",
     "",
     "Print exactly one JSON object between the markers below. The CLI will submit only this structured result back to Amistio.",
     "",
     generationResultStart,
-    '{"artifacts":[{"documentType":"plan","title":"Plan: Example","repoPath":"docs/plans/PLAN-example.md","content":"# Plan: Example\\n\\n## Goal\\n..."}]}',
+    artifactFormatPreference === "html" ? '{"artifacts":[{"documentType":"plan","contentFormat":"html","title":"Plan: Example","repoPath":"docs/html/plans/PLAN-example.html","content":"<!doctype html><html><body><h1>Plan: Example</h1></body></html>"}]}' : '{"artifacts":[{"documentType":"plan","contentFormat":"markdown","title":"Plan: Example","repoPath":"docs/plans/PLAN-example.md","content":"# Plan: Example\\n\\n## Goal\\n..."}]}',
     generationResultEnd,
     "",
     "Do not put Markdown fences around the markers. Do not claim implementation is complete."
   ].join("\n");
 }
+function artifactFormatPreferenceInstructions(preference) {
+  if (preference === "html") {
+    return "The user chose HTML. Generate .html artifacts under docs/html/<folder>/ and set contentFormat to html.";
+  }
+  if (preference === "both") {
+    return "The user chose both formats. Generate Markdown artifacts under docs/<folder>/ and matching HTML companions under docs/html/<folder>/ with contentFormat values markdown and html.";
+  }
+  if (preference === "auto") {
+    return "Choose Markdown or HTML based on the artifact content. Use Markdown for text-first docs and HTML for visual or layout-sensitive artifacts.";
+  }
+  return "The user chose Markdown. Generate Markdown artifacts under docs/<folder>/ and set contentFormat to markdown or omit it.";
+}
 function stripJsonFence(value) {
   const trimmed = value.trim();
   if (!trimmed.startsWith("```")) {
@@ -4289,7 +5055,13 @@ function formatWatchIdleLine(action, intervalSeconds) {
 }
 function shouldPrintWatchState(action, previous, nowMs, reminderMs = watchStateReminderMs) {
   const key = watchStateKey(action);
-  return !previous || previous.key !== key || nowMs - previous.printedAtMs >= reminderMs;
+  if (!previous || previous.key !== key) {
+    return true;
+  }
+  if (action.kind === "workCompleted") {
+    return false;
+  }
+  return nowMs - previous.printedAtMs >= reminderMs;
 }
 function watchStateKey(action) {
   return [action.kind, action.message, action.workItemId, action.documentId, action.runnerId].filter(Boolean).join(":");
@@ -4469,7 +5241,8 @@ async function scanLegacyDocuments(options) {
       skipped.push({ repoPath, reason: "excluded" });
       continue;
     }
-    if (!isMarkdownDocument(repoPath)) {
+    const contentFormat = inferContentFormatFromRepoPath(repoPath);
+    if (!contentFormat) {
       skipped.push({ repoPath, reason: "notMarkdown" });
       continue;
     }
@@ -4492,16 +5265,17 @@ async function scanLegacyDocuments(options) {
       skipped.push({ repoPath, reason: "unreadable" });
       continue;
     }
-    if (isAmistioManagedMarkdown(content)) {
+    if (isAmistioManagedDocument(content)) {
       skipped.push({ repoPath, reason: "alreadyManaged" });
       continue;
     }
     const documentType = classifyLegacyDocument(repoPath, content);
-    const destinationPath = uniqueDestinationPath(canonicalImportPath(repoPath, documentType), repoPath, usedDestinationPaths);
+    const destinationPath = uniqueDestinationPath(canonicalImportPath(repoPath, documentType, contentFormat), repoPath, usedDestinationPaths);
     candidates.push({
       sourcePath: repoPath,
       repoPath: destinationPath,
       documentType,
+      contentFormat,
       title: inferTitle2(content, repoPath),
       content,
       contentHash: sha256ContentHash(content)
@@ -4524,6 +5298,7 @@ function buildImportedBrainDocuments(options) {
       projectId: options.projectId,
       documentId,
       documentType: candidate.documentType,
+      contentFormat: candidate.contentFormat,
       title: candidate.title,
       status: "approved",
       repoPath: candidate.repoPath,
@@ -4602,9 +5377,6 @@ function wildcardMatch(pattern, repoPath) {
   const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "::DOUBLE_STAR_SLASH::").replace(/\*\*/g, "::DOUBLE_STAR::").replace(/\?/g, "[^/]").replace(/\*/g, "[^/]*").replace(/::DOUBLE_STAR_SLASH::/g, "(?:.*/)?").replace(/::DOUBLE_STAR::/g, ".*");
   return new RegExp(`^${escaped}$`).test(repoPath);
 }
-function isMarkdownDocument(repoPath) {
-  return /\.(md|mdx)$/i.test(repoPath);
-}
 function isExcludedRepoPath(repoPath) {
   if (isControlPlaneTemplateRepoPath(repoPath)) return true;
   if (excludedFileNames.has(repoPath)) return true;
@@ -4613,9 +5385,12 @@ function isExcludedRepoPath(repoPath) {
   const basename = segments[segments.length - 1]?.toLowerCase() ?? "";
   return basename.startsWith(".env") || basename.includes("secret") || basename.includes("token") || basename.includes("credential") || basename.endsWith(".lock");
 }
-function isAmistioManagedMarkdown(content) {
+function isAmistioManagedDocument(content) {
   const frontmatter = parseFrontmatter(content);
-  return typeof frontmatter.amistioDocumentId === "string" && frontmatter.amistioDocumentId.trim().length > 0;
+  if (typeof frontmatter.amistioDocumentId === "string" && frontmatter.amistioDocumentId.trim().length > 0) {
+    return true;
+  }
+  return /^\s*<!--[\s\S]*?amistioDocumentId\s*:/i.test(content);
 }
 function classifyLegacyDocument(repoPath, content) {
   const haystack = `${repoPath} ${inferTitle2(content, repoPath)}`.toLowerCase();
@@ -4628,7 +5403,7 @@ function classifyLegacyDocument(repoPath, content) {
   if (/\b(workflow|workflows|runbook|playbook|process|procedure|ops)\b/.test(haystack)) return "workflow";
   return "context";
 }
-function canonicalImportPath(sourcePath, documentType) {
+function canonicalImportPath(sourcePath, documentType, contentFormat) {
   if (isCanonicalControlPlanePath(sourcePath)) {
     return sourcePath;
   }
@@ -4636,7 +5411,8 @@ function canonicalImportPath(sourcePath, documentType) {
     return `docs/${sourcePath}`;
   }
   const baseSlug = slugFromPath(sourcePath);
-  return `${documentFolderByType[documentType]}/imported/${baseSlug}.md`;
+  const extension = contentFormat === "html" ? "html" : "md";
+  return `${documentFolderByType[documentType]}/imported/${baseSlug}.${extension}`;
 }
 function uniqueDestinationPath(basePath, sourcePath, usedPaths) {
   if (!usedPaths.has(basePath)) {
@@ -4651,8 +5427,8 @@ function uniqueDestinationPath(basePath, sourcePath, usedPaths) {
   return uniquePath;
 }
 function isCanonicalControlPlanePath(repoPath) {
-  const [firstSegment, secondSegment] = normalizeRepoPath4(repoPath).split("/");
-  return firstSegment === "docs" && Boolean(secondSegment && controlPlaneRoots2.includes(secondSegment));
+  const [firstSegment, secondSegment, thirdSegment] = normalizeRepoPath4(repoPath).split("/");
+  return firstSegment === "docs" && Boolean(secondSegment === "html" && thirdSegment && controlPlaneRoots2.includes(thirdSegment) || secondSegment && controlPlaneRoots2.includes(secondSegment));
 }
 function isLegacyControlPlanePath(repoPath) {
   const [firstSegment] = repoPath.split("/");
@@ -4662,6 +5438,8 @@ function inferTitle2(content, repoPath) {
   const body = stripFrontmatter(content);
   const heading = body.split("\n").find((line) => /^#\s+/.test(line))?.replace(/^#\s+/, "").trim();
   if (heading) return heading;
+  const htmlHeading = body.match(/<h1\b[^>]*>([\s\S]*?)<\/h1>/i)?.[1]?.replace(/<[^>]+>/g, "").trim();
+  if (htmlHeading) return htmlHeading;
   const basename = path10.posix.basename(repoPath, path10.posix.extname(repoPath)).replace(/[-_]+/g, " ").trim();
   return titleCase(basename || "Imported Document");
 }
@@ -4673,7 +5451,7 @@ function stripFrontmatter(content) {
   return closingLineEnd === -1 ? "" : content.slice(closingLineEnd + 1);
 }
 function slugFromPath(repoPath) {
-  const withoutExtension = repoPath.replace(/\.(md|mdx)$/i, "");
+  const withoutExtension = repoPath.replace(/\.(md|mdx|html?)$/i, "");
   const slug = withoutExtension.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 90);
   return slug || "imported-document";
 }
@@ -4772,6 +5550,7 @@ async function runOfficialCliUpdateWithRuntimeRefresh(options) {
   if (!options.restartBackgroundRunner) {
     return {
       succeeded: false,
+      stopRunner: true,
       message: `${updateResult.message} Background runner restart was not available after update. Restart the runner manually to load the updated CLI version.`,
       error: "Background runner restart hook was not provided."
     };
@@ -4786,6 +5565,7 @@ async function runOfficialCliUpdateWithRuntimeRefresh(options) {
   }
   return {
     succeeded: false,
+    stopRunner: true,
     message: `${updateResult.message} Background runner restart failed after update. Restart the runner manually to load the updated CLI version.`,
     error: restartResult.error ?? restartResult.message
   };
@@ -4907,6 +5687,186 @@ function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/implementation-handoff.ts
+import { execFile as execFile6 } from "node:child_process";
+import path13 from "node:path";
+import { promisify as promisify6 } from "node:util";
+var execFileAsync6 = promisify6(execFile6);
+async function completeImplementationHandoff(input) {
+  const run = input.commandRunner ?? defaultCommandRunner;
+  const headBranch = input.worktreeIsolation?.branch ?? input.workItem.executionBranch;
+  const baseBranch = input.baseBranch ?? input.repositoryLink?.defaultBranch ?? "main";
+  if (!headBranch) {
+    return blockedHandoff({ baseBranch, message: "Implementation handoff needs an execution branch before it can create a pull request." });
+  }
+  const common = {
+    provider: input.repositoryLink?.provider ?? "github",
+    baseBranch,
+    headBranch
+  };
+  try {
+    const unmergedFiles = await gitOutput2(run, input.worktreePath, ["diff", "--name-only", "--diff-filter=U"]);
+    if (unmergedFiles.trim()) {
+      return blockedHandoff({ ...common, message: "Implementation handoff is blocked because the worktree has unresolved merge conflicts." });
+    }
+    const status = await gitOutput2(run, input.worktreePath, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+    if (!status) {
+      return {
+        ...common,
+        status: "noChanges",
+        cleanupStatus: "notApplicable",
+        message: "Local execution completed with no repository changes to hand off."
+      };
+    }
+    const remoteName = await resolveRemoteName(run, input.worktreePath);
+    const remoteUrl = await gitOutput2(run, input.worktreePath, ["remote", "get-url", remoteName]);
+    const provider = input.repositoryLink?.provider ?? inferProvider(remoteUrl);
+    if (provider !== "github") {
+      return blockedHandoff({
+        ...common,
+        provider,
+        remoteName,
+        message: "Automated pull request handoff currently requires a GitHub remote. Commit and push manually, or link a GitHub repository."
+      });
+    }
+    await gitOutput2(run, input.worktreePath, ["add", "-A"]);
+    await gitOutput2(run, input.worktreePath, ["commit", "-m", commitSubject(input.workItem), "-m", commitBody(input)]);
+    const commitSha = await gitOutput2(run, input.worktreePath, ["rev-parse", "HEAD"]);
+    await gitOutput2(run, input.worktreePath, ["push", "--set-upstream", remoteName, headBranch]);
+    const pullRequest = await ensureGithubPullRequest(run, input.worktreePath, { baseBranch, headBranch, workItem: input.workItem, ...input.verificationSummary ? { verificationSummary: input.verificationSummary } : {} });
+    const cleanup = await cleanupWorktree(run, input);
+    return {
+      provider: "github",
+      status: "prReady",
+      baseBranch,
+      headBranch,
+      remoteName,
+      commitSha,
+      prNumber: pullRequest.number,
+      prUrl: pullRequest.url,
+      cleanupStatus: cleanup.status,
+      ...cleanup.message ? { cleanupMessage: cleanup.message } : {},
+      message: cleanup.status === "completed" ? "GitHub pull request is ready for review and the local worktree was cleaned up." : "GitHub pull request is ready for review; local worktree cleanup needs attention."
+    };
+  } catch (error) {
+    return blockedHandoff({ ...common, message: "Implementation handoff is blocked and the local worktree was preserved for recovery.", error: safeErrorMessage(error) });
+  }
+}
+async function ensureGithubPullRequest(run, cwd, input) {
+  const existing = await run("gh", ["pr", "list", "--head", input.headBranch, "--base", input.baseBranch, "--state", "open", "--json", "number,url", "--limit", "1"], { cwd });
+  const parsed = parsePullRequestList(existing.stdout);
+  if (parsed) {
+    return parsed;
+  }
+  const created = await run("gh", ["pr", "create", "--base", input.baseBranch, "--head", input.headBranch, "--title", pullRequestTitle(input.workItem), "--body", pullRequestBody(input)], { cwd });
+  const url = extractPullRequestUrl(created.stdout);
+  if (!url) {
+    throw new Error("GitHub CLI did not return a pull request URL.");
+  }
+  const number = pullRequestNumber(url);
+  if (!number) {
+    throw new Error("GitHub CLI returned a pull request URL without a parseable number.");
+  }
+  return { number, url };
+}
+async function cleanupWorktree(run, input) {
+  const status = await gitOutput2(run, input.worktreePath, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+  if (status) {
+    return { status: "failed", message: "Cleanup skipped because the worktree is not clean after PR handoff." };
+  }
+  try {
+    await gitOutput2(run, input.primaryRepoRoot || path13.dirname(input.worktreePath), ["worktree", "remove", input.worktreePath]);
+    return { status: "completed" };
+  } catch (error) {
+    return { status: "failed", message: `Cleanup failed: ${safeErrorMessage(error)}` };
+  }
+}
+async function resolveRemoteName(run, cwd) {
+  const remotes = (await gitOutput2(run, cwd, ["remote"])).split(/\r?\n/g).map((remote) => remote.trim()).filter(Boolean);
+  if (!remotes.length) {
+    throw new Error("No Git remote is configured for PR handoff.");
+  }
+  return remotes.includes("origin") ? "origin" : remotes[0];
+}
+async function gitOutput2(run, cwd, args) {
+  const result = await run("git", args, { cwd });
+  return result.stdout.trim();
+}
+function blockedHandoff(input) {
+  return {
+    status: "blocked",
+    cleanupStatus: "pending",
+    ...input
+  };
+}
+function inferProvider(remoteUrl) {
+  try {
+    return parseRepositoryCloneUrl(remoteUrl).provider ?? "other";
+  } catch {
+    return "other";
+  }
+}
+function parsePullRequestList(stdout) {
+  const parsed = JSON.parse(stdout || "[]");
+  const first = parsed[0];
+  if (typeof first?.number === "number" && typeof first.url === "string" && first.url) {
+    return { number: first.number, url: first.url };
+  }
+  return void 0;
+}
+function extractPullRequestUrl(stdout) {
+  return stdout.split(/\s+/g).find((value) => /^https:\/\/github\.com\/[^\s]+\/pull\/\d+$/i.test(value));
+}
+function pullRequestNumber(url) {
+  const match = /\/pull\/(\d+)(?:$|[?#])/.exec(url);
+  return match ? Number.parseInt(match[1], 10) : void 0;
+}
+function commitSubject(workItem) {
+  return truncate(`Amistio: ${workItem.title}`, 72);
+}
+function commitBody(input) {
+  return [
+    `Work item: ${input.workItem.workItemId}`,
+    `Implementation scope: ${input.workItem.controllingAdrId ?? input.workItem.implementationScopeId ?? "unspecified"}`,
+    "",
+    "Generated by Amistio local runner.",
+    "Do not include secrets or source patches in Amistio SaaS metadata."
+  ].join("\n");
+}
+function pullRequestTitle(workItem) {
+  return truncate(workItem.title, 120);
+}
+function pullRequestBody(input) {
+  return [
+    `Amistio work item: ${input.workItem.workItemId}`,
+    `Implementation scope: ${input.workItem.controllingAdrId ?? input.workItem.implementationScopeId ?? "unspecified"}`,
+    `Base branch: ${input.baseBranch}`,
+    `Head branch: ${input.headBranch}`,
+    "",
+    input.verificationSummary ?? "Verification summary was not reported by the local runner."
+  ].join("\n");
+}
+function truncate(value, maxLength) {
+  return value.length <= maxLength ? value : value.slice(0, maxLength - 1).trimEnd();
+}
+async function defaultCommandRunner(command, args, options) {
+  const { stdout, stderr } = await execFileAsync6(command, args, { cwd: options.cwd, maxBuffer: 1024 * 1024 });
+  return { stdout, stderr };
+}
+function safeErrorMessage(error) {
+  const scrub = (value) => redactLocalPaths(value.replace(/^Command failed:[^\n]*(\n)?/i, "").trim() || value);
+  if (typeof error === "object" && error && "stderr" in error && typeof error.stderr === "string" && error.stderr.trim()) {
+    return truncate(scrub(error.stderr.trim()), 600);
+  }
+  if (error instanceof Error) {
+    return truncate(scrub(error.message), 600);
+  }
+  return truncate(scrub(String(error)), 600);
+}
+function redactLocalPaths(value) {
+  return value.replace(/(^|[\s'"`])(\/{1,2}(?:Users|home|private|tmp|var|Volumes)\/[^\s'"`]+)/g, "$1<local-path>").replace(/(^|[\s'"`])([A-Za-z]:\\[^\s'"`]+)/g, "$1<local-path>");
+}
+
 // src/version.ts
 import { readFileSync } from "node:fs";
 function readCliPackageVersion() {
@@ -4926,7 +5886,7 @@ var DEFAULT_MAX_PREFLIGHT_ATTEMPTS = 3;
 var DEFAULT_TOOL_TIMEOUT_SECONDS = 30 * 60;
 var RUNNER_WORK_LEASE_SECONDS = 300;
 var RUNNER_WORK_LEASE_RENEWAL_MS = 12e4;
-var runnerSupportedWorkKinds = ["brainGeneration", "implementation", "planRevision", "assistantQuestion", "impactPreview", "issueDiagnosis", "securityPostureScan"];
+var runnerSupportedWorkKinds = ["brainGeneration", "implementation", "planRevision", "assistantQuestion", "impactPreview", "issueDiagnosis", "securityPostureScan", "appEvaluationScan", "projectContextRefresh"];
 program.name("amistio").description("Amistio project brain CLI").version(CLI_VERSION);
 program.command("init").description("Create Amistio control-plane folders for a new project").option("--root <path>", "Repository root", defaultRoot).action(async (options) => {
   const created = await initControlPlane(options.root);
@@ -5304,7 +6264,7 @@ program.command("run").description("Claim and run approved Amistio work locally"
       projectId: context.metadata.amistioProjectId,
       repositoryLinkId: context.metadata.repositoryLinkId,
       runnerId,
-      rootDir: path13.resolve(options.root),
+      rootDir: path14.resolve(options.root),
       apiUrl: options.apiUrl,
       args: buildBackgroundRunnerArgs(resolvedOptions)
     });
@@ -5476,7 +6436,7 @@ runnerService.command("install").description("Install a user-level startup servi
     projectId: context.metadata.amistioProjectId,
     repositoryLinkId: context.metadata.repositoryLinkId,
     runnerId,
-    rootDir: path13.resolve(options.root),
+    rootDir: path14.resolve(options.root),
     apiUrl: options.apiUrl,
     args,
     platform
@@ -5925,13 +6885,72 @@ async function runNextWorkItem({
       return recordFinalizationFailure({ apiClient, error, isolationTelemetry, projectId, repositoryLinkId, runnerId, sessionContext, toolConfig, toolName: preview.toolName, workItem: result.workItem, durationMs: Date.now() - startedAt });
     }
   }
-  const finalStatus = toolResult.exitCode === 0 ? "completed" : "failed";
+  if (result.workItem.workKind === "appEvaluationScan") {
+    try {
+      return await finalizeAppEvaluationScanWork({
+        apiClient,
+        durationMs: Date.now() - startedAt,
+        projectId,
+        repositoryLinkId,
+        runnerId,
+        sessionContext,
+        toolConfig,
+        toolName: preview.toolName,
+        toolResult,
+        workItem: result.workItem
+      });
+    } catch (error) {
+      return recordFinalizationFailure({ apiClient, error, isolationTelemetry, projectId, repositoryLinkId, runnerId, sessionContext, toolConfig, toolName: preview.toolName, workItem: result.workItem, durationMs: Date.now() - startedAt });
+    }
+  }
+  if (result.workItem.workKind === "projectContextRefresh") {
+    try {
+      return await finalizeProjectContextRefreshWork({
+        apiClient,
+        durationMs: Date.now() - startedAt,
+        projectId,
+        repositoryLinkId,
+        runnerId,
+        sessionContext,
+        toolConfig,
+        toolName: preview.toolName,
+        toolResult,
+        workItem: result.workItem
+      });
+    } catch (error) {
+      return recordFinalizationFailure({ apiClient, error, isolationTelemetry, projectId, repositoryLinkId, runnerId, sessionContext, toolConfig, toolName: preview.toolName, workItem: result.workItem, durationMs: Date.now() - startedAt });
+    }
+  }
+  let finalStatus = toolResult.exitCode === 0 ? "completed" : "failed";
   const durationMs = Date.now() - startedAt;
   const failureExcerpt = toolResult.exitCode === 0 ? void 0 : truncateLogExcerpt(toolResult.stderr || toolResult.stdout);
+  let implementationHandoff;
+  let finalMessage = `${preview.toolName} exited with code ${toolResult.exitCode}.`;
+  let finalError = failureExcerpt;
+  if (toolResult.exitCode === 0 && (result.workItem.workKind ?? "implementation") === "implementation") {
+    await recordRunnerMilestone(apiClient, projectId, result.workItem, runnerId, repositoryLinkId, {
+      status: "running",
+      summary: "Preparing GitHub PR handoff for implementation work.",
+      idempotencyKey: `runner_milestone_handoff_started_${result.workItem.workItemId}_${result.workItem.attempt}`,
+      metadata: { executionWorktreeKey: isolationTelemetry.executionWorktreeKey ?? "", executionBranch: isolationTelemetry.executionBranch ?? "" }
+    });
+    const repositoryLink = await loadWorkItemRepositoryLink(apiClient, projectId, result.workItem.repositoryLinkId ?? repositoryLinkId);
+    implementationHandoff = await completeImplementationHandoff({
+      primaryRepoRoot: root,
+      ...repositoryLink ? { repositoryLink } : {},
+      verificationSummary: "Local execution reported completion.",
+      workItem: result.workItem,
+      ...worktreeIsolation.isolation ? { worktreeIsolation: worktreeIsolation.isolation } : {},
+      worktreePath: executionRoot
+    });
+    finalStatus = implementationHandoff.status === "prReady" || implementationHandoff.status === "noChanges" ? "completed" : "blocked";
+    finalMessage = implementationHandoff.message ?? "Implementation handoff finished.";
+    finalError = implementationHandoff.error;
+  }
   const updatedToolSession = await finalizeToolSession({
     apiClient,
     projectId,
-    status: finalStatus,
+    status: toolResult.exitCode === 0 ? "completed" : "failed",
     runnerId,
     workItemId: result.workItem.workItemId,
     stdout: toolResult.stdout,
@@ -5951,8 +6970,9 @@ async function runNextWorkItem({
       tool: preview.toolName,
       ...toolResult.model ? { model: toolResult.model } : {},
       durationMs,
-      message: `${preview.toolName} exited with code ${toolResult.exitCode}.`,
+      message: finalMessage,
       ...isolationTelemetry,
+      ...finalStatus === "blocked" ? { blockerReason: finalMessage } : {},
       sessionPolicy: sessionContext.policy,
       sessionDecision: sessionContext.decision,
       sessionDecisionReason: sessionContext.reason,
@@ -5961,19 +6981,34 @@ async function runNextWorkItem({
       ...toolResult.tokensIn !== void 0 ? { tokensIn: toolResult.tokensIn } : {},
       ...toolResult.tokensOut !== void 0 ? { tokensOut: toolResult.tokensOut } : {},
       ...toolResult.costUsd !== void 0 ? { costUsd: toolResult.costUsd } : {},
-      ...failureExcerpt ? { error: failureExcerpt } : {}
+      ...implementationHandoff ? { implementationHandoff } : {},
+      ...finalError ? { error: finalError } : {}
     }
   );
   await recordRunnerMilestone(apiClient, projectId, result.workItem, runnerId, repositoryLinkId, {
     status: finalStatus,
-    summary: `${preview.toolName} exited with code ${toolResult.exitCode}.`,
+    summary: finalMessage,
     idempotencyKey: `runner_milestone_finished_${result.workItem.workItemId}_${statusResult.workItem.idempotencyKey}`,
-    metadata: { tool: preview.toolName, durationMs, exitCode: toolResult.exitCode, verificationSummary: finalStatus === "completed" ? "Local execution reported completion." : "Local execution reported failure.", executionWorktreeKey: isolationTelemetry.executionWorktreeKey ?? "", executionBranch: isolationTelemetry.executionBranch ?? "" }
+    metadata: {
+      tool: preview.toolName,
+      durationMs,
+      exitCode: toolResult.exitCode,
+      verificationSummary: finalStatus === "completed" ? "Local execution reported completion." : "Local execution reported failure.",
+      executionWorktreeKey: isolationTelemetry.executionWorktreeKey ?? "",
+      executionBranch: isolationTelemetry.executionBranch ?? "",
+      ...implementationHandoff?.status ? { handoffStatus: implementationHandoff.status } : {},
+      ...implementationHandoff?.prUrl ? { prUrl: implementationHandoff.prUrl } : {},
+      ...implementationHandoff?.cleanupStatus ? { cleanupStatus: implementationHandoff.cleanupStatus } : {}
+    }
   });
   await apiClient.sendRunnerHeartbeat(projectId, runnerId, repositoryLinkId, "online", runnerHeartbeatMetadata(toolConfig));
   const durationSeconds = Math.round(durationMs / 1e3);
   console.log(`Marked ${statusResult.workItem.workItemId} ${statusResult.workItem.status} after ${durationSeconds}s.`);
-  return { status: finalStatus, exitCode: toolResult.exitCode };
+  return { status: finalStatus, exitCode: finalStatus === "completed" ? toolResult.exitCode : 1 };
+}
+async function loadWorkItemRepositoryLink(apiClient, projectId, repositoryLinkId) {
+  const { repositoryLinks } = await apiClient.listRepositoryLinks(projectId);
+  return repositoryLinks.find((link) => link.repositoryLinkId === repositoryLinkId && link.status !== "revoked");
 }
 async function prepareWorktreeForClaimedItem({ apiClient, maxPreflightAttempts, projectId, repositoryLinkId, root, runnerId, toolConfig, workItem }) {
   if (!needsGitWorktreeIsolation(workItem)) {
@@ -6177,10 +7212,10 @@ async function executeRunnerCommand(command, context) {
   }
   return runOfficialCliUpdateWithRuntimeRefresh({
     mode: currentRunnerMode(),
-    restartBackgroundRunner: () => restartCurrentRunner(context)
+    restartBackgroundRunner: () => restartCurrentRunner(context, { useUpdatedCliExecutable: true })
   });
 }
-async function restartCurrentRunner(context) {
+async function restartCurrentRunner(context, options = {}) {
   if (currentRunnerMode() !== "background") {
     return { succeeded: false, message: "Foreground runners cannot be restarted remotely. Stop and start the local command manually." };
   }
@@ -6189,7 +7224,7 @@ async function restartCurrentRunner(context) {
     return { succeeded: false, message: "Background runner metadata was not found, so restart needs manual action." };
   }
   try {
-    const replacement = await restartRunnerDaemonProcess(metadata, context.backgroundArgs);
+    const replacement = await restartRunnerDaemonProcess(metadata, context.backgroundArgs, options.useUpdatedCliExecutable ? updatedCliRunnerLaunchOptions() : {});
     return { succeeded: true, stopRunner: true, message: `Replacement background runner started with PID ${replacement.pid}.` };
   } catch (error) {
     return { succeeded: false, message: "Background restart failed.", error: errorMessage3(error) };
@@ -6638,23 +7673,217 @@ ${toolResult.stderr}`);
   console.error(scanError ?? "Local runner security posture scan failed.");
   return { status: "failed", exitCode: toolResult.exitCode || 1 };
 }
+async function finalizeAppEvaluationScanWork({
+  apiClient,
+  durationMs,
+  projectId,
+  repositoryLinkId,
+  runnerId,
+  sessionContext,
+  toolConfig,
+  toolName,
+  toolResult,
+  workItem
+}) {
+  let scanResult = void 0;
+  let scanError;
+  if (toolResult.exitCode === 0) {
+    try {
+      scanResult = parseAppEvaluationScanResult(`${toolResult.stdout}
+${toolResult.stderr}`);
+    } catch (error) {
+      scanError = errorMessage3(error);
+    }
+  } else {
+    scanError = truncateLogExcerpt(toolResult.stderr || toolResult.stdout) || `${toolName} exited with code ${toolResult.exitCode}.`;
+  }
+  const finalStatus = scanResult ? "completed" : "failed";
+  const updatedToolSession = await finalizeToolSession({
+    apiClient,
+    projectId,
+    status: finalStatus,
+    runnerId,
+    workItemId: workItem.workItemId,
+    stdout: toolResult.stdout,
+    ...sessionContext.toolSession ? { session: sessionContext.toolSession } : {},
+    ...toolResult.messageCount !== void 0 ? { messageCount: toolResult.messageCount } : {},
+    ...toolResult.tokensIn !== void 0 ? { tokensIn: toolResult.tokensIn } : {},
+    ...toolResult.tokensOut !== void 0 ? { tokensOut: toolResult.tokensOut } : {},
+    ...toolResult.costUsd !== void 0 ? { costUsd: toolResult.costUsd } : {}
+  });
+  const sessionTelemetry = {
+    sessionPolicy: sessionContext.policy,
+    sessionDecision: sessionContext.decision,
+    sessionDecisionReason: sessionContext.reason,
+    ...updatedToolSession ? { toolSessionId: updatedToolSession.toolSessionId } : {},
+    ...updatedToolSession?.sessionGroupKey ? { sessionGroupKey: updatedToolSession.sessionGroupKey } : {}
+  };
+  if (scanResult) {
+    const result = await apiClient.submitAppEvaluationScanResult(projectId, workItem.workItemId, {
+      status: "completed",
+      runnerId,
+      idempotencyKey: `app_evaluation_${workItem.workItemId}_${randomUUID()}`,
+      result: scanResult,
+      tool: toolName,
+      durationMs,
+      ...sessionTelemetry,
+      message: `${toolName} returned an app evaluation scan.`
+    });
+    await recordRunnerMilestone(apiClient, projectId, workItem, runnerId, repositoryLinkId, {
+      status: "completed",
+      summary: `${toolName} returned an app evaluation scan.`,
+      idempotencyKey: `runner_milestone_app_evaluation_completed_${workItem.workItemId}_${result.workItem.idempotencyKey}`,
+      metadata: { tool: toolName, durationMs, findingCount: scanResult.findings.length, verificationSummary: scanResult.verificationPlan.join(" | ") }
+    });
+    await apiClient.sendRunnerHeartbeat(projectId, runnerId, repositoryLinkId, "online", runnerHeartbeatMetadata(toolConfig));
+    console.log("App evaluation scan returned for review.");
+    return { status: "completed", exitCode: 0 };
+  }
+  const failedResult = await apiClient.submitAppEvaluationScanResult(projectId, workItem.workItemId, {
+    status: "failed",
+    runnerId,
+    idempotencyKey: `app_evaluation_${workItem.workItemId}_${randomUUID()}`,
+    tool: toolName,
+    durationMs,
+    ...sessionTelemetry,
+    message: `${toolName} did not produce a valid app evaluation scan.`,
+    ...scanError ? { error: scanError } : {}
+  });
+  await recordRunnerMilestone(apiClient, projectId, workItem, runnerId, repositoryLinkId, {
+    status: "failed",
+    summary: scanError ?? `${toolName} did not produce a valid app evaluation scan.`,
+    idempotencyKey: `runner_milestone_app_evaluation_failed_${workItem.workItemId}_${failedResult.workItem.idempotencyKey}`,
+    metadata: { tool: toolName, durationMs, verificationSummary: "App evaluation output did not include valid structured JSON." }
+  });
+  await apiClient.sendRunnerHeartbeat(projectId, runnerId, repositoryLinkId, "online", runnerHeartbeatMetadata(toolConfig));
+  console.error(scanError ?? "Local runner app evaluation scan failed.");
+  return { status: "failed", exitCode: toolResult.exitCode || 1 };
+}
+async function finalizeProjectContextRefreshWork({
+  apiClient,
+  durationMs,
+  projectId,
+  repositoryLinkId,
+  runnerId,
+  sessionContext,
+  toolConfig,
+  toolName,
+  toolResult,
+  workItem
+}) {
+  let refreshResult = void 0;
+  let refreshError;
+  if (toolResult.exitCode === 0) {
+    try {
+      refreshResult = parseProjectContextRefreshResult(`${toolResult.stdout}
+${toolResult.stderr}`);
+    } catch (error) {
+      refreshError = errorMessage3(error);
+    }
+  } else {
+    refreshError = truncateLogExcerpt(toolResult.stderr || toolResult.stdout) || `${toolName} exited with code ${toolResult.exitCode}.`;
+  }
+  const finalStatus = refreshResult ? "completed" : "failed";
+  const updatedToolSession = await finalizeToolSession({
+    apiClient,
+    projectId,
+    status: finalStatus,
+    runnerId,
+    workItemId: workItem.workItemId,
+    stdout: toolResult.stdout,
+    ...sessionContext.toolSession ? { session: sessionContext.toolSession } : {},
+    ...toolResult.messageCount !== void 0 ? { messageCount: toolResult.messageCount } : {},
+    ...toolResult.tokensIn !== void 0 ? { tokensIn: toolResult.tokensIn } : {},
+    ...toolResult.tokensOut !== void 0 ? { tokensOut: toolResult.tokensOut } : {},
+    ...toolResult.costUsd !== void 0 ? { costUsd: toolResult.costUsd } : {}
+  });
+  const sessionTelemetry = {
+    sessionPolicy: sessionContext.policy,
+    sessionDecision: sessionContext.decision,
+    sessionDecisionReason: sessionContext.reason,
+    ...updatedToolSession ? { toolSessionId: updatedToolSession.toolSessionId } : {},
+    ...updatedToolSession?.sessionGroupKey ? { sessionGroupKey: updatedToolSession.sessionGroupKey } : {}
+  };
+  if (refreshResult) {
+    const result = await apiClient.submitProjectContextRefreshResult(projectId, workItem.workItemId, {
+      status: "completed",
+      runnerId,
+      idempotencyKey: `project_context_${workItem.workItemId}_${randomUUID()}`,
+      result: refreshResult,
+      tool: toolName,
+      durationMs,
+      ...sessionTelemetry,
+      message: `${toolName} returned a project context refresh.`
+    });
+    const failureSummary = projectContextRefreshSubmissionFailureSummary(result);
+    if (failureSummary) {
+      await recordRunnerMilestone(apiClient, projectId, workItem, runnerId, repositoryLinkId, {
+        status: "failed",
+        summary: failureSummary,
+        idempotencyKey: `runner_milestone_project_context_failed_${workItem.workItemId}_${result.workItem.idempotencyKey}`,
+        metadata: { tool: toolName, durationMs, sliceCount: refreshResult.slices.length, entityCount: refreshResult.entities.length, verificationSummary: "Server rejected the project context refresh result." }
+      });
+      await apiClient.sendRunnerHeartbeat(projectId, runnerId, repositoryLinkId, "online", runnerHeartbeatMetadata(toolConfig));
+      console.error(failureSummary);
+      return { status: "failed", exitCode: 1 };
+    }
+    await recordRunnerMilestone(apiClient, projectId, workItem, runnerId, repositoryLinkId, {
+      status: "completed",
+      summary: `${toolName} returned a project context refresh.`,
+      idempotencyKey: `runner_milestone_project_context_completed_${workItem.workItemId}_${result.workItem.idempotencyKey}`,
+      metadata: { tool: toolName, durationMs, sliceCount: refreshResult.slices.length, entityCount: refreshResult.entities.length, mapId: result.map?.projectContextMapId ?? "", verificationSummary: refreshResult.verificationPlan.join(" | ") }
+    });
+    await apiClient.sendRunnerHeartbeat(projectId, runnerId, repositoryLinkId, "online", runnerHeartbeatMetadata(toolConfig));
+    console.log("Project context refresh returned for review.");
+    return { status: "completed", exitCode: 0 };
+  }
+  const failedResult = await apiClient.submitProjectContextRefreshResult(projectId, workItem.workItemId, {
+    status: "failed",
+    runnerId,
+    idempotencyKey: `project_context_${workItem.workItemId}_${randomUUID()}`,
+    tool: toolName,
+    durationMs,
+    ...sessionTelemetry,
+    message: `${toolName} did not produce a valid project context refresh.`,
+    ...refreshError ? { error: refreshError } : {}
+  });
+  await recordRunnerMilestone(apiClient, projectId, workItem, runnerId, repositoryLinkId, {
+    status: "failed",
+    summary: refreshError ?? `${toolName} did not produce a valid project context refresh.`,
+    idempotencyKey: `runner_milestone_project_context_failed_${workItem.workItemId}_${failedResult.workItem.idempotencyKey}`,
+    metadata: { tool: toolName, durationMs, verificationSummary: "Project context output did not include valid structured JSON." }
+  });
+  await apiClient.sendRunnerHeartbeat(projectId, runnerId, repositoryLinkId, "online", runnerHeartbeatMetadata(toolConfig));
+  console.error(refreshError ?? "Local runner project context refresh failed.");
+  return { status: "failed", exitCode: toolResult.exitCode || 1 };
+}
 async function createRunnerWorkPrompt(apiClient, projectId, workItem) {
   if (workItem.workKind === "assistantQuestion") {
-    const [{ documents: documents2 }, { messages: messages2 }] = await Promise.all([
+    const emptyProjectContext = { maps: [], refreshes: [], misses: [] };
+    const [{ documents: documents2 }, { messages: messages2 }, context] = await Promise.all([
       apiClient.listBrainDocuments(projectId),
-      apiClient.listAssistantMessages(projectId)
+      apiClient.listAssistantMessages(projectId),
+      apiClient.listProjectContext(projectId).catch(() => emptyProjectContext)
     ]);
     const question = messages2.find((message) => message.messageId === workItem.assistantMessageId || message.id === workItem.assistantMessageId) ?? messages2.filter((message) => message.workItemId === workItem.workItemId).sort((first, second) => Date.parse(first.createdAt) - Date.parse(second.createdAt))[0];
+    const contextPack = await apiClient.buildProjectContextPack(projectId, question?.content ?? workItem.sourceWish ?? workItem.title, workItem.workItemId).catch(() => void 0);
     return createWorkExecutionPrompt(workItem, {
-      ...question ? { assistantQuestion: { question, messages: messages2, documents: documents2 } } : {}
+      ...question ? { assistantQuestion: { question, messages: messages2, documents: documents2, ...context.activeMap ? { activeMap: context.activeMap } : {}, ...contextPack ? { contextPack } : {} } } : {}
     });
   }
   if (workItem.workKind === "impactPreview") {
-    const { documents: documents2 } = await apiClient.listBrainDocuments(projectId);
+    const emptyProjectContext = { maps: [], refreshes: [], misses: [] };
+    const [{ documents: documents2 }, context] = await Promise.all([
+      apiClient.listBrainDocuments(projectId),
+      apiClient.listProjectContext(projectId).catch(() => emptyProjectContext)
+    ]);
     const implementationPrompt = workItem.impactDocumentId ? documents2.find((document) => document.documentId === workItem.impactDocumentId || document.id === workItem.impactDocumentId) : documents2.find((document) => document.frontmatter.generatedDraftId === workItem.generatedDraftId && (document.frontmatter.createsWorkItem === true || document.documentType === "prompt"));
+    const contextPack = await apiClient.buildProjectContextPack(projectId, implementationPrompt?.content ?? workItem.sourceWish ?? workItem.title, workItem.workItemId).catch(() => void 0);
     return createWorkExecutionPrompt(workItem, {
       impactPreview: {
         documents: documents2,
+        ...context.activeMap ? { activeMap: context.activeMap } : {},
+        ...contextPack ? { contextPack } : {},
         ...implementationPrompt ? { implementationPrompt } : {}
       }
     });
@@ -6678,6 +7907,25 @@ async function createRunnerWorkPrompt(apiClient, projectId, workItem) {
       securityPostureScan: { documents: documents2 }
     });
   }
+  if (workItem.workKind === "appEvaluationScan") {
+    const { documents: documents2 } = await apiClient.listBrainDocuments(projectId);
+    return createWorkExecutionPrompt(workItem, {
+      appEvaluationScan: { documents: documents2 }
+    });
+  }
+  if (workItem.workKind === "projectContextRefresh") {
+    const emptyProjectContext = { maps: [], refreshes: [], misses: [] };
+    const [{ documents: documents2 }, context] = await Promise.all([
+      apiClient.listBrainDocuments(projectId),
+      apiClient.listProjectContext(projectId).catch(() => emptyProjectContext)
+    ]);
+    return createWorkExecutionPrompt(workItem, {
+      projectContextRefresh: {
+        documents: documents2,
+        ...context.activeMap ? { activeMap: context.activeMap } : {}
+      }
+    });
+  }
   if (workItem.workKind !== "planRevision" || !workItem.reviewDocumentId) {
     return createWorkExecutionPrompt(workItem);
   }
@@ -6905,7 +8153,7 @@ function parseReasoningEffort(value) {
   throw new Error(`Expected reasoning effort auto, low, medium, high, or xhigh; received ${value}.`);
 }
 function inferRepoName(root) {
-  return path13.basename(path13.resolve(root)) || "repository";
+  return path14.basename(path14.resolve(root)) || "repository";
 }
 function createRepoFingerprint(accountId, projectId, repositoryLinkId) {
   return createHash7("sha256").update(`${accountId}:${projectId}:${repositoryLinkId}`).digest("hex");