@bastani/atomic 0.9.11-alpha.5 → 0.9.11-alpha.7

package/dist/builtin/workflows/builtin/deep-research-codebase-utils.ts

@@ -1,383 +0,0 @@
-import { readFileSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, extname, isAbsolute, join, relative } from "node:path";
-import type {
-  WorkflowOutputMode,
-  WorkflowTaskResult,
-} from "../src/shared/types.js";
-
-export const DEFAULT_MAX_PARTITIONS = 100;
-export const DEFAULT_MAX_CONCURRENCY = 100;
-const LOC_PER_PARTITION = 10_000;
-const DEFAULT_RESEARCH_DOC_DIR = "research";
-const DEEP_RESEARCH_RUN_DIR_PREFIX = ".deep-research-";
-const MAX_RESEARCH_DOC_SLUG_LENGTH = 80;
-const GIT_LS_FILES_TIMEOUT_MS = 2_000;
-
-type PromptSection = readonly [tag: string, content: string];
-
-export interface DeepResearchCodebaseResult {
-  readonly result: string;
-  readonly findings: string;
-  readonly research_doc_path: string;
-  readonly artifact_dir: string;
-  readonly manifest_path: string;
-  readonly partitions: string[];
-  readonly explorer_count: number;
-  readonly specialist_count: number;
-  readonly max_concurrency: number;
-  readonly history: string;
-}
-
-export const FILE_ONLY_OUTPUT = "file-only" satisfies WorkflowOutputMode;
-
-// Chains curated from Atomic's agentic-coding benchmark (see ralph-models.ts
-// for the frontier data). This planner uses the high-capacity synthesis roster
-// because it performs cross-codebase planning before partition fan-out.
-export const PLANNER_MODEL_CONFIG = {
-  model: "anthropic/claude-fable-5:high",
-  fallbackModels: [
-    "openai-codex/gpt-5.6-sol:xhigh",
-    "github-copilot/gpt-5.6-sol:xhigh",
-    "openai/gpt-5.6-sol:xhigh",
-    "kimi-coding/k3:max",
-    "moonshotai/kimi-k3:max",
-    "moonshotai-cn/kimi-k3:max",
-    "openai-codex/gpt-5.5:xhigh",
-    "github-copilot/gpt-5.5:xhigh",
-    "openai/gpt-5.5:xhigh",
-    "github-copilot/claude-opus-4.8 (1m):high",
-    "anthropic/claude-opus-4-8:high",
-    "cursor/claude-fable-5:high",
-    "cursor/gpt-5.6-sol:xhigh",
-    "cursor/gpt-5.5:high",
-    "cursor/claude-opus-4-8-thinking:high",
-    "xai/grok-4.5:high",
-    "cursor/grok-4.5:high",
-    "zai/glm-5.2:xhigh",
-    "zai-coding-cn/glm-5.2:xhigh",
-    "cursor/glm-5.2",
-    "openrouter/anthropic/claude-fable-5:high",
-    "openrouter/openai/gpt-5.6-sol:xhigh",
-    "openrouter/moonshotai/kimi-k3:max",
-    "openrouter/sakana/fugu-ultra:high",
-    "openrouter/openai/gpt-5.5:xhigh",
-    "openrouter/anthropic/claude-opus-4-8:high",
-    "openrouter/x-ai/grok-4.5",
-    "openrouter/z-ai/glm-5.2:xhigh",
-  ],
-  excludedTools: ["ask_user_question"],
-} as const;
-
-// gpt-5.5:low is the measured cheap-tier diamond ($1.20/task, 28 steps, 9.4k
-// output tokens). Benchmark-measured models only: opus-4.8:low (41%/$2.29)
-// and glm-5.2:high (36%/$2.84) back it up; unbenchmarked minis/haiku/flash
-// are excluded.
-export const EXPLORER_MODEL_CONFIG = {
-  model: "openai-codex/gpt-5.6-terra:high",
-  fallbackModels: [
-    "github-copilot/gpt-5.6-terra:high",
-    "openai/gpt-5.6-terra:high",
-    "openai-codex/gpt-5.5:low",
-    "github-copilot/gpt-5.5:low",
-    "openai/gpt-5.5:low",
-    "github-copilot/claude-opus-4.8 (1m):low",
-    "anthropic/claude-opus-4-8:low",
-    "cursor/gpt-5.6-terra:high",
-    "cursor/gpt-5.5:low",
-    "cursor/claude-opus-4-8-thinking:low",
-    "xai/grok-4.5:high",
-    "cursor/grok-4.5:high",
-    "zai/glm-5.2:high",
-    "zai-coding-cn/glm-5.2:high",
-    "cursor/glm-5.2",
-    "openrouter/openai/gpt-5.6-terra:high",
-    "openrouter/openai/gpt-5.5:low",
-    "openrouter/anthropic/claude-opus-4-8:low",
-    "openrouter/x-ai/grok-4.5",
-    "openrouter/z-ai/glm-5.2:xhigh",
-  ],
-  excludedTools: ["ask_user_question"],
-} as const;
-
-export function fileOnlyOutput(output: string): {
-  output: string;
-  outputMode: WorkflowOutputMode;
-} {
-  return {
-    output,
-    outputMode: FILE_ONLY_OUTPUT,
-  };
-}
-
-export function taggedPrompt(sections: readonly PromptSection[]): string {
-  return sections
-    .map(([tag, content]) => {
-      const trimmed = content.trim();
-      return `<${tag}>\n${trimmed}\n</${tag}>`;
-    })
-    .join("\n\n");
-}
-
-export function positiveInteger(
-  value: number | undefined,
-  fallback: number,
-): number {
-  return typeof value === "number" && Number.isFinite(value) && value > 0
-    ? Math.floor(value)
-    : fallback;
-}
-
-function countNewlineBytes(bytes: Uint8Array): number {
-  let total = 0;
-  for (let i = 0; i < bytes.length; i += 1) {
-    if (bytes[i] === 10) total += 1;
-  }
-  return total;
-}
-
-export function countCodebaseLines(cwd = process.cwd()): number {
-  try {
-    const gitFiles = Bun.spawnSync({
-      cmd: ["git", "ls-files", "--cached", "--others", "--exclude-standard"],
-      stdout: "pipe",
-      stderr: "pipe",
-      cwd,
-      timeout: GIT_LS_FILES_TIMEOUT_MS,
-    });
-    const files =
-      gitFiles.success && gitFiles.stdout
-        ? gitFiles.stdout
-            .toString()
-            .split("\n")
-            .map((line) => line.replace(/\r$/, ""))
-            .filter((line) => line.length > 0)
-        : [];
-
-    if (files.length === 0) return 0;
-
-    let total = 0;
-    for (const file of files) {
-      try {
-        total += countNewlineBytes(readFileSync(join(cwd, file)));
-      } catch {
-        // The line count is only a partition-sizing heuristic. Ignore files
-        // that disappear, are unreadable, or are not regular files.
-      }
-    }
-    return total;
-  } catch {
-    return 0;
-  }
-}
-
-export function calculatePartitionCap(
-  requestedMax: number,
-  codebaseLines: number,
-): number {
-  if (!Number.isFinite(codebaseLines) || codebaseLines <= 0)
-    return requestedMax;
-  return Math.max(
-    1,
-    Math.min(requestedMax, Math.ceil(codebaseLines / LOC_PER_PARTITION)),
-  );
-}
-
-export function parsePartitions(text: string, cap: number): string[] {
-  const partitions = text
-    .split(/\r?\n/)
-    .map((line) => line.replace(/^\s*(?:[-*•]|\d+[.)])\s*/, "").trim())
-    .filter((line) => line.length > 0 && !/^```/.test(line))
-    .slice(0, cap);
-
-  return partitions.length > 0 ? partitions : ["core codebase architecture"];
-}
-
-function slugifyResearchTopic(prompt: string): string {
-  const slug = prompt
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, MAX_RESEARCH_DOC_SLUG_LENGTH)
-    .replace(/-+$/g, "");
-  return slug.length > 0 ? slug : "deep-research-codebase";
-}
-
-export function defaultResearchDocPath(
-  prompt: string,
-  cwd = process.cwd(),
-  now = new Date(),
-): string {
-  const date = now.toISOString().slice(0, 10);
-  return join(
-    cwd,
-    DEFAULT_RESEARCH_DOC_DIR,
-    `${date}-${slugifyResearchTopic(prompt)}.md`,
-  );
-}
-
-function sanitizeRunId(value: string): string {
-  const sanitized = value
-    .trim()
-    .replace(/[^A-Za-z0-9._-]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-  return sanitized.length > 0 ? sanitized : "run";
-}
-
-function timestampRunId(now: Date): string {
-  return sanitizeRunId(now.toISOString().replace(/[:.]/g, "-"));
-}
-
-function suffixedPath(path: string, suffix: number): string {
-  const extension = extname(path);
-  const stem = extension.length === 0 ? path : path.slice(0, -extension.length);
-  return `${stem}-${suffix}${extension}`;
-}
-
-function isFileExistsError(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    (error as { readonly code?: string }).code === "EEXIST"
-  );
-}
-
-interface DeepResearchArtifactRoot {
-  readonly runId: string;
-  readonly artifactRoot: string;
-}
-
-export async function createArtifactRoot(
-  startedAt: Date,
-  cwd = process.cwd(),
-): Promise<DeepResearchArtifactRoot> {
-  const researchDocDir = join(cwd, DEFAULT_RESEARCH_DOC_DIR);
-  await mkdir(researchDocDir, { recursive: true });
-  const baseRunId = timestampRunId(startedAt);
-  for (let suffix = 0; ; suffix += 1) {
-    const runId = suffix === 0 ? baseRunId : `${baseRunId}-${suffix + 1}`;
-    const artifactRoot = join(
-      researchDocDir,
-      `${DEEP_RESEARCH_RUN_DIR_PREFIX}${runId}`,
-    );
-    try {
-      await mkdir(artifactRoot, { recursive: false });
-      return { runId, artifactRoot };
-    } catch (error) {
-      if (isFileExistsError(error)) continue;
-      throw error;
-    }
-  }
-}
-
-interface DeepResearchManifest {
-  readonly runId: string;
-  readonly startedAt: string;
-  readonly completedAt?: string;
-  readonly researchQuestion: string;
-  readonly finalAsset: string;
-  readonly artifacts: Record<string, string>;
-}
-
-export async function writeManifest(
-  path: string,
-  manifest: DeepResearchManifest,
-): Promise<void> {
-  await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-}
-
-export async function writeResearchDoc(
-  path: string,
-  content: string,
-): Promise<string> {
-  await mkdir(dirname(path), { recursive: true });
-
-  for (let suffix = 0; ; suffix += 1) {
-    const candidate = suffix === 0 ? path : suffixedPath(path, suffix + 1);
-    try {
-      await writeFile(candidate, content, { encoding: "utf8", flag: "wx" });
-      return candidate;
-    } catch (error) {
-      if (isFileExistsError(error)) continue;
-      throw error;
-    }
-  }
-}
-
-export async function readArtifactText(
-  path: string | undefined,
-  fallback: string,
-): Promise<string> {
-  if (path === undefined) return fallback;
-  try {
-    return await readFile(path, "utf8");
-  } catch {
-    return fallback;
-  }
-}
-
-export async function specialistHandoffFromArtifacts(
-  partition: string,
-  index: number,
-  artifactPathsByStage: ReadonlyMap<string, string>,
-): Promise<string> {
-  const i = index + 1;
-  const locator = await readArtifactText(
-    artifactPathsByStage.get(`locator-${i}`),
-    "(no locator output)",
-  );
-  const patterns = await readArtifactText(
-    artifactPathsByStage.get(`pattern-finder-${i}`),
-    "(no pattern output)",
-  );
-  const analyzer = await readArtifactText(
-    artifactPathsByStage.get(`analyzer-${i}`),
-    "(no analyzer output)",
-  );
-  const online = await readArtifactText(
-    artifactPathsByStage.get(`online-${i}`),
-    "(no online research output)",
-  );
-  return [
-    `## Partition ${i}: ${partition}`,
-    `### Locator\n${locator}`,
-    `### Pattern Finder\n${patterns}`,
-    `### Analyzer\n${analyzer}`,
-    `### Online Researcher\n${online}`,
-  ].join("\n\n");
-}
-
-export function manifestArtifactPaths(
-  artifactPathsByStage: ReadonlyMap<string, string>,
-  manifestPath: string,
-  display: (path: string) => string,
-): Record<string, string> {
-  const artifacts: Record<string, string> = {};
-  for (const [stage, path] of artifactPathsByStage) {
-    artifacts[stage] = display(path);
-  }
-  artifacts.manifest = display(manifestPath);
-  return artifacts;
-}
-
-export function findResult(
-  results: readonly WorkflowTaskResult[],
-  name: string,
-): WorkflowTaskResult | undefined {
-  return results.find(
-    (result) => result.name === name || result.stageName === name,
-  );
-}
-
-function displayPath(path: string): string {
-  return path.replace(/\\/g, "/");
-}
-
-export function displayRelativePath(path: string, fromCwd: string): string {
-  if (!isAbsolute(path)) return displayPath(path);
-  const relativePath = relative(fromCwd, path);
-  if (relativePath.length === 0) return ".";
-  if (!relativePath.startsWith("..") && !isAbsolute(relativePath)) {
-    return displayPath(relativePath);
-  }
-  return displayPath(path);
-}

package/dist/builtin/workflows/builtin/deep-research-codebase.d.ts

@@ -1,35 +0,0 @@
-import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
-
-export type DeepResearchCodebaseWorkflowInputs = WorkflowInputValues & {
-  readonly prompt: string;
-  readonly max_partitions: number;
-  readonly max_concurrency: number;
-};
-
-export type DeepResearchCodebaseWorkflowRunInputs = WorkflowInputValues & {
-  readonly prompt: string;
-  readonly max_partitions?: number;
-  readonly max_concurrency?: number;
-};
-
-export type DeepResearchCodebaseWorkflowOutputs = WorkflowOutputValues & {
-  readonly result?: string;
-  readonly findings?: string;
-  readonly research_doc_path?: string;
-  readonly artifact_dir?: string;
-  readonly manifest_path?: string;
-  readonly partitions?: string[];
-  readonly explorer_count?: number;
-  readonly specialist_count?: number;
-  readonly max_concurrency?: number;
-  readonly history?: string;
-};
-
-export type DeepResearchCodebaseWorkflowDefinition = WorkflowDefinition<
-  DeepResearchCodebaseWorkflowInputs,
-  DeepResearchCodebaseWorkflowOutputs,
-  DeepResearchCodebaseWorkflowRunInputs
->;
-
-declare const workflow: DeepResearchCodebaseWorkflowDefinition;
-export default workflow;

package/dist/builtin/workflows/builtin/deep-research-codebase.ts

@@ -1,47 +0,0 @@
-/**
- * Builtin workflow: deep-research-codebase
- *
- * Re-implements the Atomic SDK builtin topology with the pi workflow task
- * primitives: scout + research-history chain, two parallel specialist waves,
- * and a final aggregator. The local SDK does not expose Atomic's Claude-only
- * callback stage API, so the workflow models that design with ctx.task(),
- * ctx.parallel(), and ctx.chain().
- */
-
-import { Type } from "typebox";
-import { workflow } from "../src/authoring/workflow.js";
-import {
-  DEFAULT_MAX_CONCURRENCY,
-  DEFAULT_MAX_PARTITIONS,
-} from "./deep-research-codebase-utils.js";
-import { runDeepResearchCodebase } from "./deep-research-codebase-runner.js";
-
-export default workflow({
-  name: "deep-research-codebase",
-  description: "Heavy research for tasks requiring comprehensive, whole-repository context.",
-  inputs: {
-    prompt: Type.String({ description: "Research question or investigation focus for the codebase." }),
-    max_partitions: Type.Number({
-      default: DEFAULT_MAX_PARTITIONS,
-      description:
-        "Maximum number of codebase partitions to explore in parallel. Actual partitions scale by one per 10K LoC, capped by this value.",
-    }),
-    max_concurrency: Type.Number({
-      default: DEFAULT_MAX_CONCURRENCY,
-      description: "Maximum number of workflow stages to run concurrently during deep research.",
-    }),
-  },
-  outputs: {
-    result: Type.Optional(Type.String({ description: "Final Markdown research report text, matching findings." })),
-    findings: Type.Optional(Type.String({ description: "Final Markdown research report text." })),
-    research_doc_path: Type.Optional(Type.String({ description: "Public report path under research/<date>-<topic>.md." })),
-    artifact_dir: Type.Optional(Type.String({ description: "Hidden per-run handoff directory containing deep-research artifacts." })),
-    manifest_path: Type.Optional(Type.String({ description: "Manifest JSON path inside the hidden artifact directory." })),
-    partitions: Type.Optional(Type.Array(Type.String(), { description: "Codebase partitions the specialists explored." })),
-    explorer_count: Type.Optional(Type.Number({ description: "Number of partition explorer groups used." })),
-    specialist_count: Type.Optional(Type.Number({ description: "Number of specialist stages run across the research waves." })),
-    max_concurrency: Type.Optional(Type.Number({ description: "Concurrency limit used for the run." })),
-    history: Type.Optional(Type.String({ description: "Prior-research/history overview included in the final synthesis." })),
-  },
-  run: async (ctx) => await runDeepResearchCodebase(ctx),
-});

package/dist/builtin/workflows/skills/impeccable/reference/brand.md

@@ -1,108 +0,0 @@
-# Brand register
-
-When design IS the product: brand sites, landing pages, marketing surfaces, campaign pages, portfolios, long-form content, about pages. The deliverable is the design itself; a visitor's impression is the thing being made.
-
-The register spans every genre. A tech brand (Stripe, Linear, Vercel). A luxury brand (a hotel, a fashion house). A consumer product (a restaurant, a travel site, a CPG packaging page). A creative studio, an agency portfolio, a band's album page. They all share the stance (*communicate, not transact*) and diverge wildly in aesthetic. Don't collapse them into a single look.
-
-## The brand slop test
-
-If someone could look at this and say "AI made that" without hesitation, it's failed. The bar is distinctiveness; a visitor should ask "how was this made?", not "which AI made this?"
-
-Brand isn't a neutral register. AI-generated landing pages have flooded the internet, and average is no longer findable. Restraint without intent now reads as mediocre, not refined. Brand surfaces need a POV, a specific audience, a willingness to risk strangeness. Go big or go home.
-
-**The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register.
-
-Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart.
-
-## Typography
-
-### Font selection procedure
-
-Every project. Never skip.
-
-1. Read the brief. Write three concrete brand-voice words. Not "modern" or "elegant," but "warm and mechanical and opinionated" or "calm and clinical and careful." Physical-object words.
-2. List the three fonts you'd reach for by reflex. If any appear in the reflex-reject list below, reject them; they are training-data defaults and they create monoculture.
-3. Browse a real catalog (Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim, Velvetyne) with the three words in mind. Find the font for the brand as a *physical object*: a museum caption, a 1970s terminal manual, a fabric label, a cheap-newsprint children's book, a concert poster, a receipt from a mid-century diner. Reject the first thing that "looks designy."
-4. Cross-check. "Elegant" is not necessarily serif. "Technical" is not necessarily sans. "Warm" is not Fraunces. If the final pick lines up with the original reflex, start over.
-
-### Reflex-reject list
-
-Training-data defaults. Ban list. Look further:
-
-Fraunces · Newsreader · Lora · Crimson · Crimson Pro · Crimson Text · Playfair Display · Cormorant · Cormorant Garamond · Syne · IBM Plex Mono · IBM Plex Sans · IBM Plex Serif · Space Mono · Space Grotesk · Inter · DM Sans · DM Serif Display · DM Serif Text · Outfit · Plus Jakarta Sans · Instrument Sans · Instrument Serif
-
-### Reflex-reject aesthetic lanes
-
-Parallel to the font list. Currently saturated aesthetic families that have flooded brand surfaces. If a brief lands in one of these lanes without a register reason that *requires* it (a literal magazine, a literal terminal, a literal industrial signage system), it's the second-order training reflex: the trap one tier deeper than picking a Fraunces font. Look further.
-
-- **Editorial-typographic.** Display serif (often italic) + small mono labels + ruled separators + monochromatic restraint. Klim-influenced, magazine-cover affectation. By 2026, every Stripe-adjacent and Notion-adjacent brand has landed here. The fingerprint: three rule-separated columns, an italic Fraunces / Recoleta / Newsreader headline, lowercase track-spaced metadata, no imagery.
-
-(More entries land here on the same cadence the font list updates. Brutalist-utility and acid-maximalism may join when they saturate. Removing entries when they fall back below saturation is also fine.)
-
-The reflex-reject lists apply to **new design choices**. When the existing brand has already committed to a font or a lane as part of its identity, identity-preservation wins; variants on an existing surface don't second-guess what's already shipping. The reflex-reject lists are for greenfield decisions and for departure-mode variants in [live.md](live.md).
-
-### Pairing and voice
-
-Distinctive + refined is the goal. The specific shape depends on the brand, not on the brand's category. A category ("restaurant", "dev tool", "magazine", "fintech") is not a recipe; treating it as one is the first-order reflex SKILL.md warns against.
-
-Two families minimum is the rule *only* when the voice needs it. A single well-chosen family with committed weight/size contrast is stronger than a timid display+body pair.
-
-### Scale
-
-Modular scale, fluid `clamp()` for headings, ≥1.25 ratio between steps. Flat scales (1.1× apart) read as uncommitted.
-
-Light text on dark backgrounds: add 0.05–0.1 to line-height. Light type reads as lighter weight and needs more breathing room.
-
-## Color
-
-Brand surfaces have permission for Committed, Full palette, and Drenched strategies. Use them. A single saturated color spread across a hero is not excess; it's voice. A beige-and-muted-slate landing page ignores the register.
-
-- Name a real reference before picking a strategy. "Klim Type Foundry #ff4500 orange drench", "Stripe purple-on-white restraint", "Liquid Death acid-green full palette", "Mailchimp yellow full palette", "Condé Nast Traveler muted navy restraint", "Vercel pure black monochrome". Unnamed ambition becomes beige.
-- Palette IS voice. A calm brand and a restless brand should not share palette mechanics.
-- When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit.
-- Don't converge across projects. Each brand surface differentiates from the last.
-- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette.
-
-## Layout
-
-- Asymmetric compositions are one option. Break the grid intentionally for emphasis.
-- Fluid spacing with `clamp()` that breathes on larger viewports. Vary for rhythm: generous separations, tight groupings.
-- For image-led briefs (hotels, restaurants, magazines, photography), full-bleed hero imagery with overlaid menu and centered headline is a canonical move; let the photograph be the design.
-- When cards ARE the right affordance, use `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` for breakpoint-free responsiveness.
-
-## Imagery
-
-Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo.
-
-**When the brief implies imagery, you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy.
-
-- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `<div>` placeholders.
-- **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel".
-- **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one.
-- **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish".
-
-"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode.
-
-## Motion
-
-- One well-orchestrated page-load beats scattered micro-interactions, when the brand invites it. Some brands skip entrance motion entirely; the restraint is the voice.
-
-## Brand bans (on top of the shared absolute bans)
-
-- Monospace as lazy shorthand for "technical / developer." If the brand isn't technical, mono reads as costume.
-- Large rounded-corner icons above every heading. Screams template.
-- Single-family pages that picked the family by reflex, not voice. (A single family chosen deliberately is fine.)
-- All-caps body copy. Reserve caps for short labels and headings.
-- Timid palettes and average layouts. Safe = invisible.
-- Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs.
-- Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic.
-- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system.
-
-## Brand permissions
-
-Brand can afford things product can't. Take them.
-
-- Ambitious first-load motion. Reveals and typographic choreography that earn their place; not fade-on-scroll for every section.
-- Single-purpose viewports. One dominant idea per fold, long scroll, deliberate pacing.
-- Unexpected color strategies. Palette IS voice; a calm brand and a restless brand should not share palette mechanics.
-- Art direction per section. Different sections can have different visual worlds if the narrative demands it. Consistency of voice beats consistency of treatment.