@sequenceholdings/artifact-studio 0.1.12 → 0.2.0

package/dist/peer-versions.js

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const cliRequire = createRequire(import.meta.url);
+const thisModuleDir = dirname(fileURLToPath(import.meta.url));
+function readPackageVersion({ packageJsonPath, expectedName }) {
+    const raw = readFileSync(packageJsonPath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse ${packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed.name === 'string' && parsed.name !== expectedName) {
+        throw new Error(`Expected package name ${expectedName} at ${packageJsonPath}, got ${parsed.name}`);
+    }
+    if (typeof parsed.version !== 'string' || parsed.version.trim() === '') {
+        throw new Error(`Missing version in ${packageJsonPath}`);
+    }
+    return parsed.version.trim();
+}
+/**
+ * Resolve the building CLI + force-aliased atlas-ui versions from disk.
+ * Throws if either package.json is unreadable — a silent null here would
+ * undermine the observability DES-254 adds for the blast-radius scanner.
+ */
+export function resolveArtifactStudioPeerVersions() {
+    // Built code lives in `dist/`; package.json sits one level up. The same
+    // relative path works when vitest loads from `src/`.
+    const cliPackageJson = resolve(thisModuleDir, '..', 'package.json');
+    const atlasUiPackageJson = cliRequire.resolve('@sequenceholdings/atlas-ui/package.json');
+    return {
+        cliVersion: readPackageVersion({
+            packageJsonPath: cliPackageJson,
+            expectedName: '@sequenceholdings/artifact-studio',
+        }),
+        atlasUiVersion: readPackageVersion({
+            packageJsonPath: atlasUiPackageJson,
+            expectedName: '@sequenceholdings/atlas-ui',
+        }),
+    };
+}

package/dist/prepare-build.d.ts

@@ -16,6 +16,8 @@ export declare function buildControlledArtifactNpmrc(userNpmrcPath?: string): st
 export interface PrepareBuildOptions {
     /** Remote sources (--repo / --git-url) install when package.json exists. */
     remote?: boolean;
+    /** Parent environment override for deterministic security tests. */
+    sourceEnv?: NodeJS.ProcessEnv;
 }
 /**
  * Whether the build should run `pnpm install` before Vite bundles the tree.

package/dist/prepare-build.js

@@ -1,8 +1,9 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { createScrubbedChildEnv } from './child-environment.js';
 import { stripInstallControlFiles } from './sanitize-remote-tree.js';
 import { assertTrustedArtifactInstallTree } from './trusted-install.js';
 /**
@@ -82,10 +83,25 @@ export async function prepareArtifactBuildRoot(dir, opts = {}) {
     await rm(join(dir, 'node_modules'), { recursive: true, force: true });
     const configDir = await mkdtemp(join(tmpdir(), 'artifact-pnpm-'));
     const controlledNpmrc = join(configDir, '.npmrc');
-    const args = ['install', '--frozen-lockfile', '--ignore-scripts', '--prod'];
-    const userNpmrcPath = process.env.npm_config_userconfig ?? join(homedir(), '.npmrc');
+    const homeDir = join(configDir, 'home');
+    // Caches are deliberately scoped to one install. The untrusted package
+    // manager subprocess runs as the caller's uid, so a persistent cache would
+    // let one source poison dependencies consumed by a later build.
+    const npmCache = join(configDir, 'npm-cache');
+    const pnpmStore = join(configDir, 'pnpm-store');
+    const args = [
+        'install',
+        '--frozen-lockfile',
+        '--ignore-scripts',
+        '--prod',
+        '--store-dir',
+        pnpmStore,
+    ];
+    const sourceEnv = opts.sourceEnv ?? process.env;
+    const userNpmrcPath = sourceEnv.npm_config_userconfig ?? join(homedir(), '.npmrc');
     console.log(`[seq-studio] installing dependencies (frozen lockfile, prod only) via ${ARTIFACT_BUILD_PNPM}…`);
     try {
+        await mkdir(homeDir, { recursive: true });
         await writeFile(controlledNpmrc, buildControlledArtifactNpmrc(userNpmrcPath), { mode: 0o600 });
         // Run a PINNED pnpm via `npx`, not the operator's ambient `pnpm`. The
         // install must be reproducible across laptops and CI: in a bare temp clone
@@ -101,10 +117,14 @@ export async function prepareArtifactBuildRoot(dir, opts = {}) {
         execFileSync('npx', ['--yes', ARTIFACT_BUILD_PNPM, '--dir', dir, ...args], {
             cwd: configDir,
             stdio: 'inherit',
-            env: {
-                ...process.env,
-                npm_config_userconfig: controlledNpmrc,
-            },
+            env: createScrubbedChildEnv({
+                homeDir,
+                source: sourceEnv,
+                additionalEnv: {
+                    npm_config_userconfig: controlledNpmrc,
+                    npm_config_cache: npmCache,
+                },
+            }),
         });
     }
     catch (error) {

package/dist/project.d.ts

@@ -9,6 +9,9 @@ export interface ArtifactStudioSource {
     manifest: ArtifactStudioManifest;
     files: ArtifactStudioSourceFile[];
     sourceHash: string;
+    /** Path prefixes from `.artifactignore` — also enforced as non-importable by Vite. */
+    ignorePatterns: string[];
 }
 export declare function hasArtifactStudioManifest(rootDir: string): boolean;
 export declare function readArtifactStudioSource(rootDir: string): Promise<ArtifactStudioSource>;
+export declare function loadArtifactIgnorePatterns(root: string): Promise<string[]>;

package/dist/project.js

@@ -2,6 +2,7 @@ import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import yaml from 'js-yaml';
+import { ARTIFACT_IGNORE_FILE, isArtifactIgnoredPath, parseArtifactIgnore, } from './artifact-ignore.js';
 import { computeSourceHash } from './hash.js';
 import { parseArtifactStudioManifest } from './manifest.js';
 import { normalizeArtifactPath } from './paths.js';
@@ -16,7 +17,8 @@ export async function readArtifactStudioSource(rootDir) {
     const root = resolve(rootDir);
     const rawManifest = yaml.load(await readFile(join(root, 'artifact.bundle.yml'), 'utf8'));
     const manifest = parseArtifactStudioManifest(rawManifest);
-    const files = await collectSourceFiles(root);
+    const ignorePatterns = await loadArtifactIgnorePatterns(root);
+    const files = await collectSourceFiles(root, ignorePatterns);
     if (!files.some((file) => file.path === manifest.artifact.entrypoint)) {
         throw new Error(`Entrypoint file not found: ${manifest.artifact.entrypoint}`);
     }
@@ -26,22 +28,28 @@ export async function readArtifactStudioSource(rootDir) {
         files,
         // Hash the RAW manifest, not the parsed one — see computeSourceHash.
         sourceHash: computeSourceHash({ files, manifest: rawManifest }),
+        ignorePatterns,
     };
 }
-async function collectSourceFiles(root) {
+async function collectSourceFiles(root, ignorePatterns) {
     const files = [];
     async function walk(dir) {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
+            // Built-in ignores first — `normalizeArtifactPath` rejects `node_modules`
+            // (and similar) as source paths, so we must not normalize those names.
+            if (entry.isDirectory() && IGNORED_DIRS.has(entry.name))
+                continue;
             const absolute = join(dir, entry.name);
+            const path = normalizeArtifactPath(relative(root, absolute));
+            if (isArtifactIgnoredPath(path, ignorePatterns))
+                continue;
             if (entry.isDirectory()) {
-                if (!IGNORED_DIRS.has(entry.name))
-                    await walk(absolute);
+                await walk(absolute);
                 continue;
             }
             if (!entry.isFile())
                 continue;
-            const path = normalizeArtifactPath(relative(root, absolute));
             if (!isTextFile(path))
                 continue;
             files.push({
@@ -54,9 +62,17 @@ async function collectSourceFiles(root) {
     await walk(root);
     return files.sort((a, b) => a.path.localeCompare(b.path));
 }
+export async function loadArtifactIgnorePatterns(root) {
+    const ignorePath = join(root, ARTIFACT_IGNORE_FILE);
+    if (!existsSync(ignorePath))
+        return [];
+    return parseArtifactIgnore(await readFile(ignorePath, 'utf8'));
+}
 function isTextFile(path) {
     const ext = path.includes('.') ? path.slice(path.lastIndexOf('.')) : '';
-    return path === 'artifact.bundle.yml' || TEXT_EXTENSIONS.has(ext);
+    return (path === 'artifact.bundle.yml' ||
+        path === ARTIFACT_IGNORE_FILE ||
+        TEXT_EXTENSIONS.has(ext));
 }
 function inferContentType(path) {
     if (path.endsWith('.tsx') || path.endsWith('.ts'))

package/dist/runtime-chunks.d.ts

@@ -0,0 +1,4 @@
+/** Vite async-chunk namespace. Keep in sync with atlas `limits.ts` (ARTIFACT_RUNTIME_CHUNK_DIR). */
+export declare const ARTIFACT_RUNTIME_CHUNK_DIR = "chunks";
+export declare function isArtifactRuntimeChunkPath(path: string): boolean;
+export declare function assertSafeRuntimeChunkFileName(fileName: string): string;

package/dist/runtime-chunks.js

@@ -0,0 +1,15 @@
+/** Vite async-chunk namespace. Keep in sync with atlas `limits.ts` (ARTIFACT_RUNTIME_CHUNK_DIR). */
+export const ARTIFACT_RUNTIME_CHUNK_DIR = 'chunks';
+export function isArtifactRuntimeChunkPath(path) {
+    return path === ARTIFACT_RUNTIME_CHUNK_DIR || path.startsWith(`${ARTIFACT_RUNTIME_CHUNK_DIR}/`);
+}
+export function assertSafeRuntimeChunkFileName(fileName) {
+    const normalized = fileName.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!isArtifactRuntimeChunkPath(normalized)) {
+        throw new Error(`Runtime chunk path must be under ${ARTIFACT_RUNTIME_CHUNK_DIR}/: ${fileName}`);
+    }
+    if (normalized.includes('..') || normalized.startsWith('/')) {
+        throw new Error(`Invalid runtime chunk path: ${fileName}`);
+    }
+    return normalized;
+}

package/dist/sdk.d.ts

@@ -8,8 +8,18 @@ export interface SequenceApiFetchResponse<TBody = unknown> {
     status: number;
     body: TBody;
 }
+export interface SequenceApiUploadOptions {
+    timeoutMs?: number;
+    /**
+     * HTTP method for the multipart request. Defaults to POST; PUT is allowed
+     * for update-with-file routes (e.g. replacing an existing disclosure's
+     * file). Both are gated by the same `capabilities.api.write` check.
+     */
+    method?: 'POST' | 'PUT';
+}
 export interface SequenceApi {
     fetch<TBody = unknown>(path: string, options?: SequenceApiFetchOptions): Promise<SequenceApiFetchResponse<TBody>>;
+    upload<TBody = unknown>(path: string, file: File, fields?: Record<string, string>, options?: SequenceApiUploadOptions): Promise<SequenceApiFetchResponse<TBody>>;
     stream(path: string, options?: SequenceApiFetchOptions): Promise<ReadableStream<Uint8Array>>;
     get<TBody = unknown>(path: string): Promise<TBody>;
     post<TBody = unknown>(path: string, body?: unknown): Promise<TBody>;

package/dist/source-resolver.d.ts

@@ -37,6 +37,7 @@ export interface ResolvedSource {
     /** Remove any temp materialization. No-op for a local source. Never throws. */
     cleanup: () => Promise<void>;
 }
+export type SourceAuthMode = 'm2m' | 'user';
 export interface ParsedFlags {
     positional: string[];
     flags: Record<string, string | true>;
@@ -44,9 +45,9 @@ export interface ParsedFlags {
 /** True for sources that must be fetched from a remote (git-service / git-url). */
 export declare function isRemoteSpec(spec: SourceSpec): boolean;
 /**
- * Strip any userinfo (`user:token@`) from a git URL before it's logged or put
- * in an error — an https git URL can carry a PAT in its authority, and leaking
- * it to a terminal or CI log is a credential disclosure.
+ * Strip every URL component that can carry credentials before a git URL is
+ * logged or put in an error. Unparseable input is fully withheld because its
+ * structure cannot be inspected safely.
  */
 export declare function redactGitUrl(url: string): string;
 /**
@@ -57,10 +58,12 @@ export declare function redactGitUrl(url: string): string;
 export declare function parseSourceSpec(input: ParsedFlags): SourceSpec;
 /**
  * Resolve a spec to an on-disk source directory + provenance. For git-service
- * the caller must supply `baseUrl` + `token`; git-url needs neither (it shells
- * out to `git clone`); local needs nothing.
+ * the caller must supply `baseUrl` + `token` and the resolved auth mode;
+ * git-url needs no token but rejects a selected M2M principal (it shells out
+ * to `git clone`); local needs nothing.
  */
 export declare function resolveArtifactSource(spec: SourceSpec, opts?: {
+    authMode?: SourceAuthMode;
     baseUrl?: string;
     token?: string | null;
 }): Promise<ResolvedSource>;

package/dist/source-resolver.js

@@ -3,6 +3,7 @@ import { mkdirSync, rmSync } from 'node:fs';
 import { mkdtemp, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { createScrubbedChildEnv } from './child-environment.js';
 import { materializeRepo, resolveCommitSha, resolveRepo } from './git-service-client.js';
 import { gitServiceCloneUrl, resolveGitPatFromEnv, runGitClone } from './git-clone.js';
 /** True for sources that must be fetched from a remote (git-service / git-url). */
@@ -10,23 +11,23 @@ export function isRemoteSpec(spec) {
     return spec.kind !== 'local';
 }
 /**
- * Strip any userinfo (`user:token@`) from a git URL before it's logged or put
- * in an error — an https git URL can carry a PAT in its authority, and leaking
- * it to a terminal or CI log is a credential disclosure.
+ * Strip every URL component that can carry credentials before a git URL is
+ * logged or put in an error. Unparseable input is fully withheld because its
+ * structure cannot be inspected safely.
  */
 export function redactGitUrl(url) {
     try {
         const parsed = new URL(url);
-        if (parsed.username || parsed.password) {
-            parsed.username = '';
-            parsed.password = '';
-            return parsed.toString();
-        }
-        return url;
+        if (!parsed.username && !parsed.password && !parsed.search && !parsed.hash)
+            return url;
+        parsed.username = '';
+        parsed.password = '';
+        parsed.search = '';
+        parsed.hash = '';
+        return parsed.toString();
     }
     catch {
-        // Non-standard form (e.g. scp-like git@host:path) — drop a scheme://user@ prefix if present.
-        return url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@]*@/i, '$1');
+        return '<redacted-invalid-git-url>';
     }
 }
 function flagString(flags, key) {
@@ -61,27 +62,43 @@ export function parseSourceSpec(input) {
         return { kind: 'git-service', namespace: parts[0], name: parts[1], ref };
     }
     if (gitUrl) {
-        // Guard against argument injection: git treats a leading-dash URL as a flag.
-        if (gitUrl.startsWith('-'))
-            throw new Error(`--git-url must be a URL, not a flag (got "${gitUrl}").`);
+        let parsed;
+        try {
+            parsed = new URL(gitUrl);
+        }
+        catch {
+            throw new Error(`--git-url must be a credential-free HTTPS URL (got "${redactGitUrl(gitUrl)}").`);
+        }
+        if (parsed.protocol !== 'https:' ||
+            parsed.username ||
+            parsed.password ||
+            parsed.search ||
+            parsed.hash) {
+            throw new Error(`--git-url must be a credential-free HTTPS URL (got "${redactGitUrl(gitUrl)}").`);
+        }
         return { kind: 'git-url', url: gitUrl, ref };
     }
     return { kind: 'local', dir: resolve(dir ?? '.') };
 }
 /**
  * Resolve a spec to an on-disk source directory + provenance. For git-service
- * the caller must supply `baseUrl` + `token`; git-url needs neither (it shells
- * out to `git clone`); local needs nothing.
+ * the caller must supply `baseUrl` + `token` and the resolved auth mode;
+ * git-url needs no token but rejects a selected M2M principal (it shells out
+ * to `git clone`); local needs nothing.
  */
 export async function resolveArtifactSource(spec, opts = {}) {
     if (spec.kind === 'local') {
         return { dir: spec.dir, remote: false, provenance: localGitMetadata(spec.dir), cleanup: async () => { } };
     }
-    const dest = await makeTempDir();
-    const cleanup = () => removeDir(dest);
+    if (spec.kind === 'git-url' && opts.authMode === 'm2m') {
+        throw new Error('M2M/CI builds only accept platform-managed --repo sources; arbitrary --git-url sources are not trusted in CI.');
+    }
+    const workspace = await makeTempDir();
+    const dest = join(workspace, 'source');
+    const cleanup = () => removeDir(workspace);
     try {
         if (spec.kind === 'git-service') {
-            if (!opts.baseUrl || !opts.token) {
+            if (!opts.authMode || !opts.baseUrl || !opts.token) {
                 throw new Error('Deploying from --repo needs a target environment and auth. ' +
                     'Pass --env and run `seq-studio login`.');
             }
@@ -92,6 +109,16 @@ export async function resolveArtifactSource(spec, opts = {}) {
             const repo = await resolveRepo({ baseUrl: opts.baseUrl, token: opts.token, namespace: spec.namespace, name: spec.name });
             const ref = spec.ref ?? repo.defaultBranch;
             const sha = await resolveCommitSha({ baseUrl: opts.baseUrl, token: opts.token, repoId: repo.id, ref });
+            // CI/system path: the trusted M2M service account can't own a PAT (PAT
+            // issuance is gated on a human Auth0 user row), so it keeps the JSON
+            // materialize path it has always used, authenticated by its M2M token.
+            // Ignore any unrelated human PAT inherited by the parent shell: the
+            // selected principal determines both transport and audit identity.
+            if (opts.authMode === 'm2m') {
+                const count = await materializeRepo({ baseUrl: opts.baseUrl, token: opts.token, repoId: repo.id, ref: sha, destDir: dest });
+                console.log(`[seq-studio] source: ${spec.namespace}/${spec.name}@${ref} (${sha.slice(0, 10)}, ${count} file(s), M2M)`);
+                return { dir: dest, remote: true, provenance: { gitCommit: sha, gitBranch: ref, gitDirty: false }, cleanup };
+            }
             // Human path: materialize via a smart-HTTP `git clone` (one pack
             // transfer). The earlier per-blob JSON walk was O(files) serial HTTP
             // round-trips and stalled/failed on large artifacts. Smart-HTTP
@@ -104,17 +131,6 @@ export async function resolveArtifactSource(spec, opts = {}) {
                 console.log(`[seq-studio] source: ${spec.namespace}/${spec.name}@${ref} (${sha.slice(0, 10)}, git clone)`);
                 return { dir: dest, remote: true, provenance: { gitCommit: sha, gitBranch: ref, gitDirty: false }, cleanup };
             }
-            // CI/system path: the trusted M2M service account can't own a PAT (PAT
-            // issuance is gated on a human Auth0 user row), so it keeps the JSON
-            // materialize path it has always used, authenticated by its M2M token.
-            // Interactive callers (no PAT, no M2M) fall through to the hard error.
-            // TODO: teach the git-service smart-HTTP endpoint to accept the trusted
-            // M2M identity so CI can use the fast clone path too.
-            if (process.env.AUTH0_M2M_CLIENT_SECRET?.trim()) {
-                const count = await materializeRepo({ baseUrl: opts.baseUrl, token: opts.token, repoId: repo.id, ref: sha, destDir: dest });
-                console.log(`[seq-studio] source: ${spec.namespace}/${spec.name}@${ref} (${sha.slice(0, 10)}, ${count} file(s), M2M)`);
-                return { dir: dest, remote: true, provenance: { gitCommit: sha, gitBranch: ref, gitDirty: false }, cleanup };
-            }
             throw new Error('Deploying from --repo requires a git PAT. Set ATLAS_GIT_PAT to a token with the ' +
                 'repo:read scope (create one in Atlas → Settings → Tokens, or `seq-studio auth pat create`). ' +
                 'The git-service clone uses smart-HTTP, which authenticates by PAT — the same token you clone the repo with.');
@@ -137,14 +153,38 @@ export function localGitMetadata(dir) {
     };
     try {
         const gitCommit = String(execFileSync('git', ['rev-parse', 'HEAD'], gitOpts)).trim();
-        const gitBranch = String(execFileSync('git', ['branch', '--show-current'], gitOpts)).trim();
+        let gitBranch = String(execFileSync('git', ['branch', '--show-current'], gitOpts)).trim();
+        // GitHub Actions (and similar) check out a SHA → detached HEAD even when
+        // deploying main. Map that back to `main` only when HEAD equals the tip of
+        // main / origin/main — do not trust GITHUB_REF alone (workflow branch can
+        // differ from the checked-out SHA).
+        if (!gitBranch) {
+            gitBranch = resolveDetachedMainBranch({ gitOpts, gitCommit }) ?? '';
+        }
         const gitDirty = String(execFileSync('git', ['status', '--porcelain'], gitOpts)).trim().length > 0;
-        return { gitCommit, gitBranch, gitDirty };
+        return { gitCommit, gitBranch: gitBranch || null, gitDirty };
     }
     catch {
         return { gitCommit: null, gitBranch: null, gitDirty: null };
     }
 }
+/**
+ * When `git branch --show-current` is empty (detached HEAD), return `main` if
+ * HEAD is exactly the tip of a local/remote main ref — otherwise null.
+ */
+function resolveDetachedMainBranch({ gitOpts, gitCommit, }) {
+    for (const ref of ['refs/heads/main', 'main', 'refs/remotes/origin/main', 'origin/main']) {
+        try {
+            const tip = String(execFileSync('git', ['rev-parse', ref], gitOpts)).trim();
+            if (tip === gitCommit)
+                return 'main';
+        }
+        catch {
+            // ref missing in this clone (shallow / no remotes) — try the next one
+        }
+    }
+    return null;
+}
 async function makeTempDir() {
     const dir = await mkdtemp(join(tmpdir(), 'artifact-src-'));
     // Canonicalize: the Vite html plugin emits the entry file name relative to
@@ -163,9 +203,18 @@ async function removeDir(dir) {
     }
 }
 function cloneGitUrl(url, ref, dest) {
+    const homeDir = join(resolve(dest, '..'), 'home');
+    mkdirSync(homeDir, { recursive: true });
     const opts = {
         stdio: ['ignore', 'pipe', 'pipe'],
         encoding: 'utf8',
+        env: createScrubbedChildEnv({
+            homeDir,
+            additionalEnv: {
+                GIT_CONFIG_NOSYSTEM: '1',
+                GIT_TERMINAL_PROMPT: '0',
+            },
+        }),
     };
     const git = (args) => String(execFileSync('git', args, opts)).trim();
     try {

package/dist/templates/react-vite/AGENTS.md

@@ -0,0 +1,90 @@
+# Sequence Artifact Studio app
+
+This is a sandboxed iframe SPA that runs inside Atlas and talks to Atlas backend routes through a postMessage bridge exposed as `seq.api.*` from `@sequenceholdings/artifact-studio`. No direct network access, no API keys in the bundle — everything goes through the bridge, and every endpoint the artifact uses must be declared in `artifact.bundle.yml`.
+
+## Three rules that bite
+
+1. **Envelope unwrap.** Atlas wraps every CRM-style response in `{ success: true, data: T }`. The bridge passes that envelope through raw — it does **not** unwrap automatically. Route every read/write through `unwrap<T>()` in `src/lib/api.ts`:
+   ```ts
+   import { unwrap, seq } from './lib/api'
+   const customer = await unwrap<Customer>(seq.api.get(`/api/crm/customers/${id}`))
+   ```
+   For endpoints with extra envelope fields (pagination `meta`, warnings), drop to `seq.api.fetch` and read `res.body` directly.
+
+2. **FormData blocker.** `seq.api.fetch` `JSON.stringify`s any non-string `body` value, which silently turns `FormData` into `"{}"`. For multipart uploads, use `seq.api.upload(path, file, fields?, options?)`; the bridge constructs `FormData` in the trusted host and returns the usual `{ ok, status, body }` envelope.
+
+3. **Capability matcher: exact paths, `/*` prefix wildcards, and single-segment `*` patterns.** `{id}` template forms do **not** match. List both the bare path and the prefix wildcard for broad resources, or use a least-privilege segment pattern for dynamic routes:
+   ```yaml
+   - /api/crm/customers
+   - /api/crm/customers/*
+   - /api/lattice/runs/*/advance
+   ```
+
+## Prerequisite
+
+None — `seq-studio artifact init <dir>` works from any directory; no monorepo checkout is required. The template lists `@sequenceholdings/artifact-studio` and `@sequenceholdings/atlas-ui` in **devDependencies** for local editor/type-check tooling only. `seq-studio artifact build|deploy` bundles against the CLI's own pinned copies of `react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, and `@sequenceholdings/atlas-ui`, and resolves `@sequenceholdings/artifact-studio` to a virtual `window.seq` module. Remote deploys (`--repo` / `--git-url`) run `pnpm install --prod` for **app-specific** `dependencies` only (e.g. `recharts`, `reactflow`) from the artifact lockfile.
+
+## Package manager
+
+Use **pnpm** for artifacts you will deploy from git — `seq-studio artifact build|deploy --repo/--git-url` runs `pnpm install --frozen-lockfile --prod` when `package.json` is present, so commit `pnpm-lock.yaml`. Local editor-only installs can use another package manager, but pnpm keeps Sequence's `minimumReleaseAge` supply-chain quarantine in effect (see the studio-cli README). If you have a stale checkout from the old `file:`-link era, `rm -rf node_modules` and reinstall.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `artifact.bundle.yml` | Capability manifest — every API path the artifact calls: exact paths, `/*` prefix wildcards, or single-segment `*` patterns |
+| `src/main.tsx` | Providers: `QueryClientProvider` → `PortalContainerProvider` → `App` |
+| `src/App.tsx` | Entrypoint UI |
+| `src/lib/api.ts` | `unwrap<T>` envelope helper + re-export of `seq` |
+| `src/styles.css` | Tailwind v4 + `@sequenceholdings/atlas-ui/tokens.css` (+ v2 sheets; build injects them when missing) |
+| `vite.config.ts` | Vite + React + Tailwind v4 plugin |
+
+## Defaults
+
+- UI: prefer `@sequenceholdings/atlas-ui` primitives (`Button`, `Card`, `Input`, `Dialog`, `Select`, `Checkbox`, `DropdownMenu`, `KpiTile`, `Switch`, …) over raw Tailwind. The design-system cutover made `Select`, `Checkbox`, `DropdownMenu`, `Command`, `Calendar`, `ScrollArea`, `Table`, and the Task family first-class exports — use them directly; fall back to `Popover` compositions or native controls only when a component is genuinely missing.
+- Routing: `HashRouter`. Mount routes at `/`, not at the Atlas app prefix.
+- Data: React Query is wired in `src/main.tsx`. Use `useQuery` / `useMutation` against `unwrap(seq.api.*)`.
+- Icons: do **not** add third-party deps like `@tabler/icons-react`. Deploys from git (`--repo` / `--git-url`) build a bare tree — `seq-studio` runs `pnpm install --prod` from your lockfile, then aliases platform peers (`react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, `@sequenceholdings/atlas-ui`). List only app-specific imports (e.g. `recharts`) in `dependencies`; do not add file/workspace `@sequenceholdings/*` specs in git-service repos, because remote installs only accept registry semver specs. Inline SVG components in `src/icons.tsx`.
+
+## Tokens — colour comes from semantic roles, never a raw ramp
+
+This app bundles `@sequenceholdings/atlas-ui/tokens.css` and re-themes per tenant for free. Reach for a **semantic role** and colour follows the host brand and light/dark automatically.
+
+**Never** use the numbered `black-*` / `white-*` opacity scales (`text-black-40`, `bg-black-6`, `border-black-10`), raw Tailwind neutrals (`gray|slate|zinc|neutral|stone-N`), arbitrary hex in class strings (`bg-[#1f2937]`), or `var(--black-*)` / `var(--color-black-*)`. These are **retired** — post-cutover they resolve to nothing or to a fixed ink that won't flip in dark. Bare `text-white` / `bg-black` and opacity modifiers like `bg-foreground/10` stay legal; only the numbered steps and raw palettes are banned. There is no old→new lookup table on purpose — pick by *what the element is and what it sits on*.
+
+| Situation | Role |
+|---|---|
+| The page surface | `bg-background` — the page only, never a panel |
+| Bordered/rounded panel, card, list | `bg-card` — a border is not a surface; every bordered container needs an explicit surface |
+| Inset well inside a card (code block, read-only value) | `bg-muted` |
+| Form field (input, textarea, select trigger) | `bg-field` |
+| Interactive / hover fill | `bg-accent` / `bg-surface-hover` |
+| Selected / active / focus state fill | `bg-foreground/8`–`bg-foreground/15` overlay |
+| Modal scrim behind a dialog | `bg-overlay` — never `bg-foreground/N` (washes lighter in dark) |
+| Primary text | `text-foreground` |
+| Resting nav items, meta rows | `text-foreground-secondary` |
+| Section labels, captions | `text-muted-foreground` |
+| Standard border | `border-border` (form controls: `border-input`) |
+
+Surfaces **nest** — never repeat a rung (`bg-card` inside `bg-card` is invisible): `bg-background` (page) → `bg-card` (panel, + border + `shadow-xs` to lift) → `bg-muted` (inset well).
+
+**Dual-runtime.** Inside Atlas the artifact runs in its own iframe and inherits nothing — the runtime posts the host's resolved brand in as inline custom properties (theme channel + `data-tokens`). Standalone `vite dev` has no host, so the artifact must still render on the base semantic roles. **Do not** bundle `tokens.v2.tenants.css`, hardcode an opco's brand, or add `[data-theme]` selectors — that pins the artifact to one tenant.
+
+## Bridge methods
+
+Two primitives on `seq.api`:
+
+- `seq.api.fetch(path, options?)` returns `{ ok, status, body }` — does not throw on non-2xx. Use when you need the status (e.g. handle 409) or the raw envelope with extra fields like `meta`.
+- `seq.api.request(method, path, body?)` throws on non-2xx and returns parsed JSON. Sugar wrappers `seq.api.get / .post / .patch / .delete` are thin shells around `request`, so they also throw.
+
+Wrap reads/writes that should auto-throw through `unwrap()` in `src/lib/api.ts`. Drop to `seq.api.fetch` when you need pagination `meta` or status inspection.
+
+## Lattice embed context
+
+When the artifact is served from a Lattice human node (the **Tasks/Inbox** task surface, or the builder Artifacts tab), `seq.lattice.context()` tells you which run/node/step you're rendering for:
+
+```ts
+const { runId, nodeId, stepId, processId } = seq.lattice.context()
+```
+
+It's **synchronous** (the host injects this into the sandbox up front — no bridge round trip) and each field is `null` when unavailable. The Inbox provides all four; the builder Artifacts tab has no live `stepId`; a standalone open has no context at all. Use it instead of hand-parsing `window.location` — that's the sanctioned, stable accessor, and you don't need to declare anything in `artifact.bundle.yml` for it. To read step-scoped data, pass `runId`/`stepId` to the relevant Atlas endpoint (which still authorizes the caller server-side).

package/dist/templates/react-vite/CLAUDE.md

@@ -1,66 +1,7 @@
 # Sequence Artifact Studio app
 
-This is a sandboxed iframe SPA that runs inside Atlas and talks to Atlas backend routes through a postMessage bridge exposed as `seq.api.*` from `@sequenceholdings/artifact-studio`. No direct network access, no API keys in the bundle — everything goes through the bridge, and every endpoint the artifact uses must be declared in `artifact.bundle.yml`.
+Agent instructions for this artifact live in `AGENTS.md` — one file every coding agent reads
+(Cursor and Codex load `AGENTS.md` natively; the import below pulls it in for Claude Code).
+Add or edit guidance in `AGENTS.md`, not here.
 
-## Three rules that bite
-
-1. **Envelope unwrap.** Atlas wraps every CRM-style response in `{ success: true, data: T }`. The bridge passes that envelope through raw — it does **not** unwrap automatically. Route every read/write through `unwrap<T>()` in `src/lib/api.ts`:
-   ```ts
-   import { unwrap, seq } from './lib/api'
-   const customer = await unwrap<Customer>(seq.api.get(`/api/crm/customers/${id}`))
-   ```
-   For endpoints with extra envelope fields (pagination `meta`, warnings), drop to `seq.api.fetch` and read `res.body` directly.
-
-2. **FormData blocker.** `seq.api.fetch` `JSON.stringify`s any non-string `body` value, which silently turns `FormData` into `"{}"`. For uploads, base64-encode the bytes and POST as JSON, or patch the Atlas bridge first.
-
-3. **Capability matcher: exact paths, `/*` prefix wildcards, and single-segment `*` patterns.** `{id}` template forms do **not** match. List both the bare path and the prefix wildcard for broad resources, or use a least-privilege segment pattern for dynamic routes:
-   ```yaml
-   - /api/crm/customers
-   - /api/crm/customers/*
-   - /api/lattice/runs/*/advance
-   ```
-
-## Prerequisite
-
-None — `seq-studio artifact init <dir>` works from any directory; no monorepo checkout is required. The template lists `@sequenceholdings/artifact-studio` and `@sequenceholdings/atlas-ui` in **devDependencies** for local editor/type-check tooling only. `seq-studio artifact build|deploy` bundles against the CLI's own pinned copies of `react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, and `@sequenceholdings/atlas-ui`, and resolves `@sequenceholdings/artifact-studio` to a virtual `window.seq` module. Remote deploys (`--repo` / `--git-url`) run `pnpm install --prod` for **app-specific** `dependencies` only (e.g. `recharts`, `reactflow`) from the artifact lockfile.
-
-## Package manager
-
-Use **pnpm** for artifacts you will deploy from git — `seq-studio artifact build|deploy --repo/--git-url` runs `pnpm install --frozen-lockfile --prod` when `package.json` is present, so commit `pnpm-lock.yaml`. Local editor-only installs can use another package manager, but pnpm keeps Sequence's `minimumReleaseAge` supply-chain quarantine in effect (see the studio-cli README). If you have a stale checkout from the old `file:`-link era, `rm -rf node_modules` and reinstall.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `artifact.bundle.yml` | Capability manifest — every API path the artifact calls: exact paths, `/*` prefix wildcards, or single-segment `*` patterns |
-| `src/main.tsx` | Providers: `QueryClientProvider` → `PortalContainerProvider` → `App` |
-| `src/App.tsx` | Entrypoint UI |
-| `src/lib/api.ts` | `unwrap<T>` envelope helper + re-export of `seq` |
-| `src/styles.css` | Tailwind v4 + `@sequenceholdings/atlas-ui/tokens.css` |
-| `vite.config.ts` | Vite + React + Tailwind v4 plugin |
-
-## Defaults
-
-- UI: prefer `@sequenceholdings/atlas-ui` primitives (`Button`, `Card`, `Input`, `Dialog`, `Select`, `Checkbox`, `DropdownMenu`, `KpiTile`, `Switch`, …) over raw Tailwind. The design-system cutover made `Select`, `Checkbox`, `DropdownMenu`, `Command`, `Calendar`, `DatePicker`, `ScrollArea`, `Table`, and the Task family first-class exports — use them directly; fall back to `Popover` compositions or native controls only when a component is genuinely missing.
-- Routing: `HashRouter`. Mount routes at `/`, not at the Atlas app prefix.
-- Data: React Query is wired in `src/main.tsx`. Use `useQuery` / `useMutation` against `unwrap(seq.api.*)`.
-- Icons: do **not** add third-party deps like `@tabler/icons-react`. Deploys from git (`--repo` / `--git-url`) build a bare tree — `seq-studio` runs `pnpm install --prod` from your lockfile, then aliases platform peers (`react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, `@sequenceholdings/atlas-ui`). List only app-specific imports (e.g. `recharts`) in `dependencies`; do not add file/workspace `@sequenceholdings/*` specs in git-service repos, because remote installs only accept registry semver specs. Inline SVG components in `src/icons.tsx`.
-
-## Bridge methods
-
-Two primitives on `seq.api`:
-
-- `seq.api.fetch(path, options?)` returns `{ ok, status, body }` — does not throw on non-2xx. Use when you need the status (e.g. handle 409) or the raw envelope with extra fields like `meta`.
-- `seq.api.request(method, path, body?)` throws on non-2xx and returns parsed JSON. Sugar wrappers `seq.api.get / .post / .patch / .delete` are thin shells around `request`, so they also throw.
-
-Wrap reads/writes that should auto-throw through `unwrap()` in `src/lib/api.ts`. Drop to `seq.api.fetch` when you need pagination `meta` or status inspection.
-
-## Lattice embed context
-
-When the artifact is served from a Lattice human node (the **Tasks/Inbox** task surface, or the builder Artifacts tab), `seq.lattice.context()` tells you which run/node/step you're rendering for:
-
-```ts
-const { runId, nodeId, stepId, processId } = seq.lattice.context()
-```
-
-It's **synchronous** (the host injects this into the sandbox up front — no bridge round trip) and each field is `null` when unavailable. The Inbox provides all four; the builder Artifacts tab has no live `stepId`; a standalone open has no context at all. Use it instead of hand-parsing `window.location` — that's the sanctioned, stable accessor, and you don't need to declare anything in `artifact.bundle.yml` for it. To read step-scoped data, pass `runId`/`stepId` to the relevant Atlas endpoint (which still authorizes the caller server-side).
+@AGENTS.md