@bastani/atomic 0.9.11-alpha.6 → 0.9.11-alpha.8

package/examples/sdk/09-api-keys-and-oauth.ts

@@ -1,52 +1,46 @@
 /**
  * API Keys and OAuth
  *
- * Configure API key resolution via AuthStorage and ModelRegistry.
+ * Configure credential and model resolution through ModelRuntime.
  */
 
-import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@bastani/atomic";
-
-// Default: AuthStorage uses ~/.atomic/agent/auth.json (legacy ~/.pi/agent/auth.json also works)
-// ModelRegistry loads built-in + custom models from ~/.atomic/agent/models.json (legacy ~/.pi/agent/models.json also works)
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+import { createAgentSession, ModelRuntime, SessionManager } from "@bastani/atomic";
 
+// Default: createAgentSession builds a runtime from the active agent directory's
+// auth.json and models.json.
 const { session: defaultAuthSession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry,
 });
-console.log("Session with default auth storage and model registry");
+console.log("Session with default credential and model configuration");
 defaultAuthSession.dispose();
 
-// Custom auth storage location
-const customAuthStorage = AuthStorage.create("/tmp/my-app/auth.json");
-const customModelRegistry = ModelRegistry.create(customAuthStorage, "/tmp/my-app/models.json");
-
+// Custom credential and model configuration locations
+const customRuntime = await ModelRuntime.create({
+	authPath: "/tmp/my-app/auth.json",
+	modelsPath: "/tmp/my-app/models.json",
+});
 const { session: customAuthSession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage: customAuthStorage,
-	modelRegistry: customModelRegistry,
+	modelRuntime: customRuntime,
 });
-console.log("Session with custom auth storage location");
+console.log("Session with custom credential and model configuration");
 customAuthSession.dispose();
 
 // Runtime API key override (not persisted to disk)
-authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+const runtimeKeyRuntime = await ModelRuntime.create();
+await runtimeKeyRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
 const { session: runtimeKeySession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry,
+	modelRuntime: runtimeKeyRuntime,
 });
 console.log("Session with runtime API key override");
 runtimeKeySession.dispose();
 
 // No models.json - only built-in models
-const simpleRegistry = ModelRegistry.inMemory(authStorage);
+const builtinsOnlyRuntime = await ModelRuntime.create({ modelsPath: null });
 const { session: builtInModelsSession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry: simpleRegistry,
+	modelRuntime: builtinsOnlyRuntime,
 });
 console.log("Session with only built-in models");
 builtInModelsSession.dispose();

package/examples/sdk/12-full-control.ts

@@ -6,26 +6,25 @@
 
 import { getModel } from "@earendil-works/pi-ai/compat";
 import {
-	AuthStorage,
 	createAgentSession,
 	createExtensionRuntime,
-	ModelRegistry,
+	ModelRuntime,
 	type ResourceLoader,
 	SessionManager,
 	SettingsManager,
 } from "@bastani/atomic";
 
-// Custom auth storage location
-const authStorage = AuthStorage.create("/tmp/my-agent/auth.json");
+// Custom credential location with no custom models.json
+const modelRuntime = await ModelRuntime.create({
+	authPath: "/tmp/my-agent/auth.json",
+	modelsPath: null,
+});
 
 // Runtime API key override (not persisted)
 if (process.env.MY_ANTHROPIC_KEY) {
-	authStorage.setRuntimeApiKey("anthropic", process.env.MY_ANTHROPIC_KEY);
+	await modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_ANTHROPIC_KEY);
 }
 
-// Model registry with no custom models.json
-const modelRegistry = ModelRegistry.inMemory(authStorage);
-
 const model = getModel("anthropic", "claude-sonnet-4-5");
 if (!model) throw new Error("Model not found");
 
@@ -46,7 +45,7 @@ const resourceLoader: ResourceLoader = {
 	getSystemPrompt: () => `You are a minimal assistant.
 Available: read, bash. Be concise.`,
 	getAppendSystemPrompt: () => [],
-	extendResources: () => {},
+	extendResources: async () => {},
 	reload: async () => {},
 };
 
@@ -55,8 +54,7 @@ const { session } = await createAgentSession({
 	agentDir: "/tmp/my-agent",
 	model,
 	thinkingLevel: "off",
-	authStorage,
-	modelRegistry,
+	modelRuntime,
 	resourceLoader,
 	tools: ["read", "bash"],
 	sessionManager: SessionManager.inMemory(cwd),

package/examples/sdk/README.md

@@ -34,50 +34,48 @@ bun examples/sdk/01-minimal.ts
 ```typescript
 import { getModel } from "@earendil-works/pi-ai/compat";
 import {
-  AuthStorage,
   createAgentSession,
   DefaultResourceLoader,
-  ModelRegistry,
+  ModelRuntime,
   SessionManager,
   SettingsManager,
 } from "@bastani/atomic";
 
-// Auth and models setup
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+// Credential and model setup
+const modelRuntime = await ModelRuntime.create();
 
-// Minimal
-const { session } = await createAgentSession({ authStorage, modelRegistry });
+// Minimal (omitting modelRuntime uses the active agent directory)
+const { session } = await createAgentSession();
 
 // Custom model
 const model = getModel("anthropic", "claude-opus-4-5");
-const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });
+const { session } = await createAgentSession({ model, thinkingLevel: "high", modelRuntime });
 
 // Modify prompt
 const loader = new DefaultResourceLoader({
   systemPromptOverride: (base) => `${base}\n\nBe concise.`,
 });
 await loader.reload();
-const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry });
+const { session } = await createAgentSession({ resourceLoader: loader, modelRuntime });
 
 // Read-only
-const { session } = await createAgentSession({ tools: ["read", "search", "find", "ls"], authStorage, modelRegistry });
+const { session } = await createAgentSession({ tools: ["read", "search", "find", "ls"], modelRuntime });
 
 // Defaults minus one tool
-const { session } = await createAgentSession({ excludedTools: ["ask_user_question"], authStorage, modelRegistry });
+const { session } = await createAgentSession({ excludedTools: ["ask_user_question"], modelRuntime });
 
 // In-memory
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
-  authStorage,
-  modelRegistry,
+  modelRuntime,
 });
 
 // Full control
-const customAuth = AuthStorage.create("/my/app/auth.json");
-customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
-const customRegistry = ModelRegistry.create(customAuth);
-
+const customRuntime = await ModelRuntime.create({
+  authPath: "/my/app/auth.json",
+  modelsPath: "/my/app/models.json",
+});
+await customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
 const resourceLoader = new DefaultResourceLoader({
   systemPromptOverride: () => "You are helpful.",
   extensionFactories: [myExtension],
@@ -89,8 +87,7 @@ await resourceLoader.reload();
 
 const { session } = await createAgentSession({
   model,
-  authStorage: customAuth,
-  modelRegistry: customRegistry,
+  modelRuntime: customRuntime,
   resourceLoader,
   tools: ["read", "bash", "my_tool"],
   customTools: [myTool],
@@ -111,8 +108,7 @@ await session.prompt("Hello");
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `authStorage` | `AuthStorage.create()` | Credential storage |
-| `modelRegistry` | `ModelRegistry.create(authStorage)` | Model registry |
+| `modelRuntime` | Runtime created from the active agent directory | Credential and model runtime override |
 | `cwd` | `process.cwd()` | Working directory |
 | `agentDir` | `~/.atomic/agent` (legacy `~/.pi/agent` also works) | Config directory |
 | `model` | From settings/first available | Model to use |

package/npm-shrinkwrap.json

@@ -1,15 +1,15 @@
 {
 	"name": "@bastani/atomic",
-	"version": "0.9.11-alpha.6",
+	"version": "0.9.11-alpha.8",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@bastani/atomic",
-			"version": "0.9.11-alpha.6",
+			"version": "0.9.11-alpha.8",
 			"license": "MIT",
 			"dependencies": {
-				"@bastani/atomic-natives": "0.9.11-alpha.6",
+				"@bastani/atomic-natives": "0.9.11-alpha.8",
 				"@dbos-inc/dbos-sdk": "4.23.6",
 				"@earendil-works/pi-agent-core": "^0.82.1",
 				"@earendil-works/pi-ai": "^0.82.1",
@@ -515,16 +515,16 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives": {
-			"version": "0.9.11-alpha.6",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.11-alpha.6.tgz",
+			"version": "0.9.11-alpha.8",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.11-alpha.8.tgz",
 			"license": "MIT",
 			"optionalDependencies": {
-				"@bastani/atomic-natives-darwin-arm64": "0.9.11-alpha.6",
-				"@bastani/atomic-natives-darwin-x64": "0.9.11-alpha.6",
-				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.11-alpha.6",
-				"@bastani/atomic-natives-linux-x64-gnu": "0.9.11-alpha.6",
-				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.11-alpha.6",
-				"@bastani/atomic-natives-win32-x64-msvc": "0.9.11-alpha.6"
+				"@bastani/atomic-natives-darwin-arm64": "0.9.11-alpha.8",
+				"@bastani/atomic-natives-darwin-x64": "0.9.11-alpha.8",
+				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.11-alpha.8",
+				"@bastani/atomic-natives-linux-x64-gnu": "0.9.11-alpha.8",
+				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.11-alpha.8",
+				"@bastani/atomic-natives-win32-x64-msvc": "0.9.11-alpha.8"
 			},
 			"engines": {
 				"bun": ">=1.3.14",
@@ -532,8 +532,8 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives-darwin-arm64": {
-			"version": "0.9.11-alpha.6",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.11-alpha.6.tgz",
+			"version": "0.9.11-alpha.8",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.11-alpha.8.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -544,8 +544,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-darwin-x64": {
-			"version": "0.9.11-alpha.6",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.11-alpha.6.tgz",
+			"version": "0.9.11-alpha.8",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.11-alpha.8.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -556,8 +556,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-gnu": {
-			"version": "0.9.11-alpha.6",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.11-alpha.6.tgz",
+			"version": "0.9.11-alpha.8",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.11-alpha.8.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -571,8 +571,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-gnu": {
-			"version": "0.9.11-alpha.6",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.11-alpha.6.tgz",
+			"version": "0.9.11-alpha.8",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.11-alpha.8.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -586,8 +586,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-arm64-msvc": {
-			"version": "0.9.11-alpha.6",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.11-alpha.6.tgz",
+			"version": "0.9.11-alpha.8",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.11-alpha.8.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -598,8 +598,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-x64-msvc": {
-			"version": "0.9.11-alpha.6",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.11-alpha.6.tgz",
+			"version": "0.9.11-alpha.8",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.11-alpha.8.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.11-alpha.6",
+  "version": "0.9.11-alpha.8",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -78,7 +78,7 @@
     "prepublishOnly": "bun run clean && bun run build && bun run shrinkwrap"
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.11-alpha.6",
+    "@bastani/atomic-natives": "0.9.11-alpha.8",
     "@dbos-inc/dbos-sdk": "4.23.6",
     "@earendil-works/pi-agent-core": "^0.82.1",
     "@earendil-works/pi-ai": "^0.82.1",

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.

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

@@ -1,105 +0,0 @@
-# Codex: Visual Direction & Asset Production
-
-This file is loaded by `$impeccable craft` when the harness has native image generation (currently Codex via `image_gen`). Other harnesses skip it. It covers the two craft steps that depend on real image generation: landing the visual direction, and producing the raster assets the implementation will compose.
-
-Read this *before* generating any images. The order matters, and the per-step user pauses are what keep generated imagery from drifting away from the brief.
-
-### Four stop points before code
-
-Steps A through D each end with the user. Do not advance past any of them on your own read of the situation.
-
-1. **STOP after Step A questions.** Wait for answers.
-2. **STOP after Step B palette generation.** Wait for "confirm palette."
-3. **STOP after Step C mocks.** Wait for direction approval or delegation.
-4. **Only after Step D approves a direction** do you return to craft.md Step 4 and write code.
-
-Prior shape approval does **not** satisfy any of these. Shape's "confirm or override" advances you into Step A; it is not a substitute for it.
-
-## Step A: Explore Directions with the User
-
-Before generating anything, run a brief direction conversation grounded in the shape brief.
-
-**Step A is required even when shape just produced a confirmed brief.** The shape questions and Step A questions cover different ground: shape pins purpose, content, scope; Step A pins palette, atmosphere, and named visual references for the comps you're about to generate. The only time you can skip Step A is when the user has already answered these exact palette/atmosphere/reference questions in the same session.
-
-Ask **2-3 targeted questions** about visual lane, color strategy, atmosphere, and named anchor references. Don't enumerate generic menus; tie each question to the shape brief's answers. Example shape-grounded questions:
-
-- "Brief says 'specimen-page restraint.' Are we closer to a quiet typographic page or a wider editorial spread with hero imagery?"
-- "Palette strategy from shape was 'Committed.' Which one color carries the surface (a brand-driven pick rather than a default warm-or-cool framing)? (And no, the answer isn't a cream/sand body bg; that's the saturated AI default.)"
-
-**STOP and wait for answers.** These pin the palette before any pixel gets generated. Do not proceed to Step B until the user has responded.
-
-## Step B: Generate the Brand Palette First
-
-Generate **one** palette artifact before any mocks. This is a small, focused image: typography pairing on the chosen background, primary + accent color swatches, one signature ornament or motif. Single image, single pass.
-
-Why palette first: mocks generated against a vague color sense produce noise that drowns out the structural decisions. A confirmed palette is the first concrete contract for everything downstream.
-
-Show the palette to the user. Ask one question: "This is the palette I'm locking in for the mocks. Confirm, or call out what to shift?"
-
-**STOP and wait for confirmation.** Do not generate mocks against an unconfirmed palette. "Probably good enough" is the wrong call here; the palette is the contract for everything downstream.
-
-## Step C: Generate 1-3 Visual Mocks Against the Palette
-
-Once the palette is confirmed, generate **1 to 3** high-fidelity north-star comps. Each mock must use the confirmed palette and typography. Mocks differ in *structural* direction (hierarchy, topology, density, composition), not in color or motif.
-
-- Brand work: push visual identity, composition, mood, and signature motifs.
-- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure.
-- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero.
-
-Use the `image_gen` tool directly (or via the imagegen skill when available). Don't ask the user to install anything.
-
-## Step D: Approval Loop
-
-Show the comps. Ask what carries forward. Iterate until **one direction is approved** or the user explicitly delegates.
-
-**STOP and wait for the approval or the delegation.** Do not begin Step E or return to craft.md Step 4 until a single direction is named. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste.
-
-Before moving to assets, summarize what to carry into code and what *not* to literalize from the mock. This is the handoff between visual exploration and semantic implementation.
-
-## Step E: Mock Fidelity Inventory
-
-Inventory the approved mock's major visible ingredients. For each, decide implementation: semantic HTML/CSS/SVG, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission.
-
-Common ingredients to inventory:
-
-- Hero silhouette and dominant composition
-- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.)
-- Nav and primary CTA treatment
-- Section sequence, especially the second fold
-- Image-native content the concept depends on
-- Typography, density, color/material treatment, motion cues
-
-Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong.
-
-If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, bullets, or copy, stop and fix it. That's a broken implementation, not a harmless interpretation.
-
-Don't substitute a different hero composition or visual driver post-approval without user sign-off.
-
-## Step F: Asset Slicing via the Asset Producer
-
-Raster ingredients identified in Step E need clean production assets. Use the bundled `impeccable_asset_producer` subagent rather than producing inline.
-
-Spawn it as a scoped subagent. If you do not have explicit permission to use agents, stop and ask:
-
-```text
-Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step?
-```
-
-Pass to the agent:
-
-- Approved mock path or screenshot reference
-- Crop paths or a contact sheet with crop ids
-- Output directory
-- Required dimensions, format, transparency needs
-- Avoid list
-- Notes on what should remain semantic HTML/CSS/SVG instead of raster
-
-Attach image generation capability to the spawned agent when the harness supports it. Do **not** load image-generation reference material into the parent thread.
-
-Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode.
-
-Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; reach for real, generated, or stock imagery when the mock or subject matter calls for actual visual content.
-
-## After This File
-
-Once Steps A through F are complete, return to `craft.md` Step 5 (Build to Production Quality). The implementation builds against the confirmed palette, approved mock, and the assets the producer wrote.