appostle-installer 0.0.18 → 0.0.20

package/dist/appostle.js

@@ -1922,6 +1922,10 @@ function toAgentPayload(agent, options) {
     title: options?.title ?? null,
     labels: agent.labels,
     internal: agent.internal,
+    // Forward archivedAt on the live broadcast so paired clients (e.g. mobile)
+    // see the archive land — without this, only the device that ran the
+    // archive mutation knows about it.
+    archivedAt: agent.archivedAt ?? null,
     // Surface ownership so the client can render an owner badge / detect
     // "shared with me" agents. `sharedWithUserIds` deliberately stays off
     // the snapshot — only owners read the full ACL, via the dedicated
@@ -3203,6 +3207,7 @@ var RoleMoveResponseSchema = z10.object({
 var BrandScopeSchema = z10.literal("project");
 var BrandVariableTypeSchema = z10.enum([
   "color",
+  "gradient",
   "font",
   "asset",
   "text",
@@ -19463,11 +19468,53 @@ var ClaudeAgentSession = class {
       // sub-agents stop announcing them as suspected prompt injections. See
       // getSystemReminderGuidance for the full rationale.
       getSystemReminderGuidance(),
-      "Default response shape: open with a short, scannable plain-English read. 2\u20134 short sentences, one idea each, no comma-chained clauses or em-dash pile-ups. When the read covers 3+ discrete points, use bullets instead of prose. Then the technical detail in dense form (paths, line refs, code) without narration. Don't explain what well-named code already explains. Skip the shape for trivial questions.",
-      "For multi-step work with independent chunks, spawn Task subagents instead of doing every tool call yourself. Run them in parallel when chunks don't depend on each other. Keeps your main context lean.",
+      //
+      //
+      //
+      //
+      // ╔══════════════════════════════════════════════════════════════════╗
+      // ║  CUSTOM INSTRUCTIONS — add new system prompt lines below here  ║
+      // ║  Each line is a quoted string: "your instruction here",        ║
+      // ╚══════════════════════════════════════════════════════════════════╝
+      //
+      //
+      //
+      //
+      "Default response shape: open with a short, scannable plain-English read. 2\u20134 short sentences, one idea each, no comma-chained clauses or em-dash pile-ups. When the read covers 3+ discrete points, use bullets instead of prose. Then the technical detail in dense form (paths, line refs, code) without narration. Don\u2019t explain what well-named code already explains. Skip the shape for trivial questions.",
+      //
       "When the user sends `>learn`, re-explain your previous message in plain English only \u2014 1 short paragraph that helps them build the mental model. No code, no file references, no technical repeat.",
+      //
+      //
+      //
+      //
+      // ╔══════════════════════════════════════════════════════════════════╗
+      // ║  END CUSTOM INSTRUCTIONS — don't edit below this line          ║
+      // ╚══════════════════════════════════════════════════════════════════╝
+      //
+      //
+      //
+      //
       this.config.systemPrompt?.trim()
     ].filter((entry) => typeof entry === "string" && entry.length > 0).join("\n\n");
+    const appostleAgents = {
+      researcher: {
+        description: "Use this agent when you need to explore unfamiliar code, trace data flow across modules, search broadly across the codebase, or read more than 2 files you haven't seen yet. Delegate investigation work here to keep the main conversation context lean.",
+        prompt: "You are a codebase researcher. Your job is to investigate, trace, and report findings \u2014 never edit files. Read code, grep for patterns, follow imports, and build a clear picture. Report back a concise summary of what you found: key files, relevant code paths, and your conclusion. Keep your report under 300 words unless the investigation is complex.",
+        model: "sonnet"
+      },
+      refactorer: {
+        description: "Use this agent for refactors that touch more than 2 files \u2014 renames, migrations, pattern replacements, moving code between modules. Delegate multi-file changes here to isolate the blast radius.",
+        prompt: "You are a refactoring specialist. Make the requested changes across all affected files. Be thorough \u2014 update imports, references, types, and tests. Run typecheck after changes if available. Report what you changed and any issues found."
+      },
+      reviewer: {
+        description: "Use this agent to review code for bugs, security issues, performance problems, or style violations. Use it before committing large changes or when the user asks for a review.",
+        prompt: "You are a code reviewer. Analyze the code for correctness, security vulnerabilities (OWASP top 10), performance issues, and adherence to the project's coding standards. Be specific \u2014 cite file paths and line numbers. Flag severity: critical, warning, or nitpick. Keep the review focused and actionable."
+      },
+      debugger: {
+        description: "Use this agent to investigate bugs \u2014 read logs, trace error paths, check database state, reproduce issues. Delegate debugging here when the root cause isn't obvious from a quick look.",
+        prompt: "You are a debugger. Your job is to find the root cause, not patch symptoms. Check real data first \u2014 logs, network requests, database state. Trace the full lifecycle of the bug. Present your findings: root cause, evidence, and a proposed minimal fix. Do not edit files unless explicitly asked."
+      }
+    };
     const claudeBinary = await findExecutable("claude");
     this.logger.debug(
       {
@@ -19485,7 +19532,7 @@ var ClaudeAgentSession = class {
       // bypass launch capability available so later setPermissionMode("bypassPermissions")
       // calls do not fail after a model/thinking/rewind-driven restart.
       allowDangerouslySkipPermissions: true,
-      agents: this.defaults?.agents,
+      agents: { ...appostleAgents, ...this.defaults?.agents },
       canUseTool: this.handlePermissionRequest,
       ...claudeBinary ? { pathToClaudeCodeExecutable: claudeBinary } : {},
       // Use Claude Code preset system prompt and load CLAUDE.md files
@@ -35111,6 +35158,7 @@ ${original}`;
 // ../server/src/server/brand/token-generator.ts
 import { z as z37 } from "zod";
 var HEX6 = /^#[0-9a-f]{6}$/i;
+var CSS_GRADIENT = /^(linear|radial|conic)-gradient\(/i;
 var TokensResponseSchema = z37.object({
   tokens: z37.record(z37.string(), z37.string())
 });
@@ -35186,6 +35234,31 @@ function buildPrompt2(args) {
     }
   }
   const tokensToFill = args.unlockedTokens.map((v) => `- ${v.key}`).join("\n");
+  const gradientSection = args.unlockedGradients.length > 0 ? [
+    "",
+    "Gradient tokens to fill (values must be valid CSS gradient strings,",
+    "e.g. linear-gradient(135deg, #c52669 0%, #ff6b35 100%)):",
+    ...args.unlockedGradients.map((v) => `- ${v.key}`),
+    "",
+    "Gradient key glossary:",
+    "- gradient.primary \u2014 the brand's signature gradient, built from the",
+    "  most prominent palette colours. Used for hero backgrounds, feature",
+    "  highlights, and primary decorative surfaces.",
+    "- gradient.accent  \u2014 a secondary gradient for interactive states,",
+    "  hover effects, or accent surfaces. Distinct from primary but",
+    "  harmonious with the palette.",
+    "- gradient.subtle  \u2014 a very soft, low-contrast gradient for subtle",
+    "  background washes \u2014 card backgrounds, section tints. Should feel",
+    "  almost invisible; same hue family as bg-base with minimal shift.",
+    "",
+    "Include gradient values in the same JSON under the 'tokens' key,",
+    "alongside the hex tokens. Gradient values are CSS gradient strings."
+  ].join("\n") : "";
+  const lockedGradientSection = args.lockedGradients.length > 0 ? [
+    "",
+    "Locked gradients \u2014 DO NOT include these in your output:",
+    ...args.lockedGradients.map((v) => `- ${v.key}: ${v.value}`)
+  ].join("\n") : "";
   const lockedSection = args.lockedTokens.length > 0 ? [
     "",
     "Locked tokens \u2014 DO NOT include these in your output. The user has",
@@ -35232,13 +35305,15 @@ function buildPrompt2(args) {
     "Tokens to fill (every value must be a #RRGGBB lowercase hex string):",
     tokensToFill,
     lockedSection,
+    gradientSection,
+    lockedGradientSection,
     directionSection,
     "",
     "Return JSON only with the shape:",
-    '{ "tokens": { "<token-key>": "#rrggbb", ... } }',
+    '{ "tokens": { "<token-key>": "#rrggbb or css-gradient-string", ... } }',
     "",
-    "Output ONLY the unlocked tokens listed above. Do not include the locked",
-    "tokens, do not invent new keys, do not output anything outside the JSON.",
+    "Output ONLY the unlocked tokens and gradients listed above. Do not include",
+    "locked entries, do not invent new keys, do not output anything outside the JSON.",
     "Never use a hex value from a colour marked OFF."
   ].filter((line) => line !== "").join("\n");
 }
@@ -35252,9 +35327,12 @@ async function generateAndApplyBrandTokens(options) {
   const allVars = colorsBrand.variables;
   const paletteVars = allVars.filter((v) => v.key.startsWith("color."));
   const tokenVars = allVars.filter((v) => v.key.startsWith("token."));
+  const gradientVars = allVars.filter((v) => v.type === "gradient");
   const unlockedTokens = tokenVars.filter((v) => !v.locked);
   const lockedTokens = tokenVars.filter((v) => v.locked);
-  if (unlockedTokens.length === 0) {
+  const unlockedGradients = gradientVars.filter((v) => !v.locked);
+  const lockedGradients = gradientVars.filter((v) => v.locked);
+  if (unlockedTokens.length === 0 && unlockedGradients.length === 0) {
     logger.info({ brandPath }, "brand-tokens: nothing to generate (all tokens locked)");
     return { generatedCount: 0 };
   }
@@ -35265,6 +35343,8 @@ async function generateAndApplyBrandTokens(options) {
     paletteVars,
     unlockedTokens,
     lockedTokens,
+    unlockedGradients,
+    lockedGradients,
     mode,
     userPrompt: prompt
   });
@@ -35290,14 +35370,19 @@ async function generateAndApplyBrandTokens(options) {
     }
     throw error;
   }
-  const unlockedKeySet = new Set(unlockedTokens.map((v) => v.key));
+  const unlockedTokenKeySet = new Set(unlockedTokens.map((v) => v.key));
+  const unlockedGradientKeySet = new Set(unlockedGradients.map((v) => v.key));
   const acceptedUpdates = /* @__PURE__ */ new Map();
   for (const [key, value] of Object.entries(response.tokens)) {
-    if (!unlockedKeySet.has(key)) continue;
     if (typeof value !== "string") continue;
     const trimmed = value.trim();
-    if (!HEX6.test(trimmed)) continue;
-    acceptedUpdates.set(key, trimmed.toLowerCase());
+    if (unlockedTokenKeySet.has(key)) {
+      if (!HEX6.test(trimmed)) continue;
+      acceptedUpdates.set(key, trimmed.toLowerCase());
+    } else if (unlockedGradientKeySet.has(key)) {
+      if (!CSS_GRADIENT.test(trimmed)) continue;
+      acceptedUpdates.set(key, trimmed);
+    }
   }
   if (acceptedUpdates.size === 0) {
     logger.warn(
@@ -35334,6 +35419,7 @@ import path20 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { z as z38 } from "zod";
 var QA_FILENAME = "layout-qa.md";
+var PROMPT_FILENAME = "layout-prompt.md";
 var MAX_LOOKUP_LEVELS = 10;
 var ROLE_FILE_RELATIVE = ".appostle/brand/assets/role/brand-layout-role.md";
 async function findFileUpward(filename) {
@@ -35442,111 +35528,37 @@ function buildStructuralContext(allBrands) {
   return lines.length > 0 ? lines.join("\n") : "(No structural context established yet.)";
 }
 var TARGET_QUESTIONS = 7;
-var EMBEDDED_QA_FALLBACK = `## Compositional Philosophy
-- What's the single-sentence design philosophy that should govern every layout decision?
-- What's the ratio of whitespace to content density you're after?
-
-## Hero Behavior
-- How should the hero section behave? Full viewport takeover, contained module, asymmetric split?
-- Should the hero have scroll-triggered behavior or stay static?
-
-## Section Variation & Flow
-- How many distinct section types should the page cycle through?
-- Should any sections break out of the main container (full-bleed moments)?
-
-## Density & Spacing
-- How tight should content be packed within sections?
-- How much vertical breathing room between major sections?
-
-## Grid System
-- What grid philosophy \u2014 strict 12-column, asymmetric, modular, or freeform?
-
-## Containers & Cards
-- What's your card philosophy \u2014 flat, elevated, outlined, or glassmorphic?
-
-## Image Treatment
-- What role do images play \u2014 hero-level, supporting, or minimal?
-
-## CTA Strategy
-- How many CTAs per page and what's the hierarchy?
-
-## Mobile Behavior
-- How should the desktop layout transform on mobile?
-
-## Prohibitions & Bans
-- What design patterns are absolutely forbidden?
-- Any CSS properties or techniques that are banned?`;
+async function loadSpecFile(filename, logger) {
+  const filePath = await findFileUpward(filename);
+  if (!filePath) {
+    throw new Error(
+      `layout-generator: ${filename} not found by walking up from ${fileURLToPath2(import.meta.url)}. This file is the canonical spec and must exist at the appostle repo root.`
+    );
+  }
+  try {
+    const content = await fs12.readFile(filePath, "utf8");
+    logger.debug({ filePath }, `layout-generator: loaded ${filename} from disk`);
+    return content;
+  } catch (err) {
+    throw new Error(
+      `layout-generator: failed to read ${filename} at ${filePath}: ${err.message}`
+    );
+  }
+}
 async function loadQaQuestions(logger) {
-  const filePath = await findFileUpward(QA_FILENAME);
-  if (filePath) {
-    try {
-      const content = await fs12.readFile(filePath, "utf8");
-      logger.debug({ filePath }, "layout-generator: loaded Q&A questions from disk");
-      return content;
-    } catch (err) {
-      logger.warn(
-        { err, filePath },
-        "layout-generator: failed to read Q&A file; using embedded fallback"
-      );
-    }
+  return loadSpecFile(QA_FILENAME, logger);
+}
+async function loadLayoutPrompt(logger) {
+  return loadSpecFile(PROMPT_FILENAME, logger);
+}
+function interpolateTemplate(template, vars) {
+  let out = template;
+  for (const [key, value] of Object.entries(vars)) {
+    out = out.split(`{{${key}}}`).join(value);
   }
-  return EMBEDDED_QA_FALLBACK;
+  return out;
 }
-var ROLE_GENERATION_INSTRUCTIONS = `You are an elite art director generating a complete design role document. This document will be injected wholesale into an AI agent's context to give it a dense, opinionated compositional voice \u2014 the way lordesign-brutalist or lordesign-soft gives a builder an entire design philosophy.
-
-The output must be a SINGLE cohesive markdown document (NOT JSON, NOT key-value pairs). It reads like a design manifesto \u2014 dense, opinionated, specific enough that two different builders reading it would produce nearly identical structural decisions.
-
-## Required sections (use these exact headings)
-
-# Brand Layout Role
-
-## Compositional Philosophy
-The north star. 3-5 sentences describing the fundamental spatial personality.
-
-## Hero Behavior
-Exact rules for hero sections \u2014 dimensions, content placement, image treatment, scroll behavior, what's forbidden.
-
-## Section Variation & Flow
-How consecutive sections differ. Allowed arrangements. How many types cycle. Full-bleed rules.
-
-## Density Philosophy
-Where dense, where airy, specific spacing ratios, padding rules.
-
-## Vertical Rhythm
-Section height strategy, padding patterns, oscillation rules, breathing room logic.
-
-## Grid System
-Column philosophy, alignment rules, breakpoint behavior, visible vs invisible structure.
-
-## Container & Card Rules
-Borders, shadows, corners, nesting rules, elevation hierarchy.
-
-## Image Treatment
-Aspect ratios, size constraints, cropping rules, filter/overlay rules, frequency.
-
-## CTA Strategy
-Frequency per page, hierarchy, styling constraints, placement rules.
-
-## Mobile Behavior
-Breakpoint strategy, what collapses vs stacks, density changes, navigation transformation.
-
-## Bans
-The most powerful section. At least 20 specific prohibitions at EVERY level:
-- CSS-level (specific properties, values, patterns)
-- Component-level (specific UI patterns forbidden)
-- Layout-level (spatial patterns forbidden)
-- Content-level (content patterns forbidden)
-- Interaction-level (motion/animation patterns forbidden)
-
-Each ban on its own line starting with "\u2022". Be ruthlessly specific \u2014 "no gradients" is vague, "no linear-gradient except single-stop overlays on hero images" is useful.
-
-## Critical quality bar
-- Every rule must be specific enough to resolve an ambiguous decision
-- No generic advice ("keep it clean") \u2014 only actionable constraints
-- The bans section alone should have 20+ items
-- Rules should reference specific CSS properties, pixel values, viewport units where applicable
-- The document should be 50-100 rules total across all sections`;
-function buildQaSystemPrompt(questions) {
+function buildQaSystemPrompt(questions, layoutPromptSpec) {
   return `You are a chill creative director doing a quick vibe check on someone's layout taste.
 
 CONTEXT:
@@ -35580,10 +35592,11 @@ When done=false, return:
 { "done": false, "question": "Short question?", "options": ["Option A", "Option B", "Option C", "Option D"] }
 
 When done=true, return:
-{ "done": true, "roleDocument": "# Brand Layout Role\\n\\n## Compositional Philosophy\\n..." }
+{ "done": true, "roleDocument": "# Brand Layout Role\\n\\n## Enemy\\n..." }
 
-The roleDocument must be a complete markdown document following this structure:
-${ROLE_GENERATION_INSTRUCTIONS}`;
+The roleDocument must be a complete markdown document following the structure and rules below. Treat the Q&A conversation as the user's intent; there is no current role document yet.
+
+${layoutPromptSpec}`;
 }
 async function layoutQaNext(options) {
   const { agentManager, workspaceRoot, brandPath, conversation, logger } = options;
@@ -35592,7 +35605,13 @@ async function layoutQaNext(options) {
   if (!brand) throw new Error(`Brand file not found at ${brandPath}`);
   const structuralContext = buildStructuralContext(brands);
   const questions = await loadQaQuestions(logger);
-  const qaSystemPrompt = buildQaSystemPrompt(questions);
+  const layoutPromptTemplate = await loadLayoutPrompt(logger);
+  const layoutPromptSpec = interpolateTemplate(layoutPromptTemplate, {
+    structuralContext,
+    currentValues: "(No existing role document \u2014 this is initial generation from a Q&A conversation.)",
+    userPrompt: "(See Q&A conversation below for the user's intent.)"
+  });
+  const qaSystemPrompt = buildQaSystemPrompt(questions, layoutPromptSpec);
   const convLines = conversation.map((m) => `${m.role === "assistant" ? "AI" : "User"}: ${m.content}`).join("\n\n");
   const userAnswerCount = conversation.filter((m) => m.role === "user").length;
   const prompt = [
@@ -35643,24 +35662,12 @@ async function generateAndApplyLayout(options) {
   if (!brand) throw new Error(`Brand file not found at ${brandPath}`);
   const structuralContext = buildStructuralContext(brands);
   const existingRole = await readRoleFile(workspaceRoot);
-  const prompt = [
-    ROLE_GENERATION_INSTRUCTIONS,
-    "",
-    "## Structural context (sibling brand files)",
+  const layoutPromptTemplate = await loadLayoutPrompt(logger);
+  const prompt = interpolateTemplate(layoutPromptTemplate, {
     structuralContext,
-    "",
-    existingRole ? `## Current role document
-
-${existingRole}` : "(No existing role document \u2014 generate from scratch.)",
-    "",
-    "## User's refinement prompt",
-    userPrompt,
-    "",
-    "This is a REFINEMENT. The user already has a role document (shown above). Their prompt refines, evolves, or redirects \u2014 it does NOT start from scratch unless they explicitly say so.",
-    "",
-    'Return ONLY a JSON object: { "roleDocument": "the complete updated markdown document" }',
-    "No markdown fences. No explanation."
-  ].join("\n");
+    currentValues: existingRole ?? "(No existing role document \u2014 generate from scratch.)",
+    userPrompt
+  });
   let response;
   try {
     response = await generateStructuredAgentResponseWithFallback({