@sequenceholdings/artifact-studio 0.4.0 → 0.5.0

package/dist/server/request-context.d.ts

@@ -4,6 +4,12 @@ export declare const ARTIFACT_REQUEST_CONTEXT_HEADER = "x-sequence-artifact-cont
 export declare const ARTIFACT_RUNTIME_TOKEN_HEADER = "x-sequence-artifact-runtime";
 export declare const ARTIFACT_SERVER_REQUEST_PATH = "/api/artifact-studio/server/request";
 export declare const ARTIFACT_CONTEXT_MAX_AGE_SECONDS = 60;
+/**
+ * Lattice managed-server invocations last up to the node timeout (300s). A
+ * browser context stays at {@link ARTIFACT_CONTEXT_MAX_AGE_SECONDS}. The longer
+ * window applies only when the signed context names a Lattice run.
+ */
+export declare const ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS = 300;
 /** Public request context. No bearer credentials or secret values belong here. */
 export declare const artifactRequestContextSchema: z.ZodObject<{
     v: z.ZodLiteral<1>;

package/dist/server/request-context.js

@@ -5,6 +5,12 @@ export const ARTIFACT_REQUEST_CONTEXT_HEADER = 'x-sequence-artifact-context';
 export const ARTIFACT_RUNTIME_TOKEN_HEADER = 'x-sequence-artifact-runtime';
 export const ARTIFACT_SERVER_REQUEST_PATH = '/api/artifact-studio/server/request';
 export const ARTIFACT_CONTEXT_MAX_AGE_SECONDS = 60;
+/**
+ * Lattice managed-server invocations last up to the node timeout (300s). A
+ * browser context stays at {@link ARTIFACT_CONTEXT_MAX_AGE_SECONDS}. The longer
+ * window applies only when the signed context names a Lattice run.
+ */
+export const ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS = 300;
 const id = z.string().min(1).max(255);
 const originSchema = z.string().max(2048).refine(value => {
     try {
@@ -46,7 +52,10 @@ export const artifactRequestContextSchema = z.object({
 }).strict().superRefine((value, ctx) => {
     if (value.aud !== `artifact:${value.projectId}`)
         ctx.addIssue({ code: 'custom', message: 'Invalid Artifact audience' });
-    if (value.exp <= value.iat || value.exp - value.iat > ARTIFACT_CONTEXT_MAX_AGE_SECONDS)
+    const maxAge = value.lattice.runId !== null
+        ? ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS
+        : ARTIFACT_CONTEXT_MAX_AGE_SECONDS;
+    if (value.exp <= value.iat || value.exp - value.iat > maxAge)
         ctx.addIssue({ code: 'custom', message: 'Invalid Artifact context lifetime' });
     if (value.mode === 'development' ? !value.devSessionId || value.deploymentId !== null : !value.deploymentId || value.devSessionId !== null)
         ctx.addIssue({ code: 'custom', message: 'Artifact runtime identity does not match its mode' });

package/dist/server.d.ts

@@ -1,8 +1,12 @@
 import 'server-only';
 export { createArtifactServerClient, ArtifactServerError } from './server/client.js';
-export type { ArtifactOrmOperations, ArtifactServerClient, ArtifactServerFetchOptions } from './server/client.js';
+export type { ArtifactAtlasRefusal } from './server/errors.js';
+export type { ArtifactAuditEvent, ArtifactOrmOperations, ArtifactOrmOptions, ArtifactProcessAdvance, ArtifactProcessAdvanceResult, ArtifactProcessArtifactRef, ArtifactProcessAssign, ArtifactProcessAssignResult, ArtifactProcessDefinition, ArtifactProcessDescribeQuery, ArtifactProcessEdge, ArtifactProcessHumanNode, ArtifactProcessNode, ArtifactProcessNodeBase, ArtifactProcessNodeState, ArtifactProcessPrincipal, ArtifactProcessPrincipalSearch, ArtifactProcessPrincipals, ArtifactProcessRun, ArtifactProcessRunRecord, ArtifactProcessRunSnapshot, ArtifactProcessRunsQuery, ArtifactProcessRunViewerChange, ArtifactProcessRunViewers, ArtifactProcessStart, ArtifactProcessStepRecord, ArtifactProcessTask, ArtifactProcessTasksQuery, ArtifactServerAudit, ArtifactServerClient, ArtifactServerFetchOptions, ArtifactServerFlags, ArtifactServerProcesses, } from './server/client.js';
+export { ARTIFACT_AUDIT_ACTIONS, ARTIFACT_AUDIT_RESOURCES_PER_EVENT, ARTIFACT_FLAGS_PER_REQUEST, ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, ARTIFACT_PROCESS_PRINCIPAL_TYPES, ARTIFACT_PROCESS_PRINCIPALS_PER_CALL, ARTIFACT_PROCESS_RUN_STATUSES, ARTIFACT_PROCESS_RUNS_LIMIT, ARTIFACT_PROCESS_TASK_VIEWS, ARTIFACT_PROCESS_TASKS_LIMIT, } from './server/broker-contract.js';
+export type { ArtifactAuditAction, ArtifactProcessPrincipalType, ArtifactProcessRunStatus, ArtifactProcessTaskView, } from './server/broker-contract.js';
 export { getArtifactRequestContext, readArtifactRuntimeConfig } from './server/runtime-config.js';
 export type { ArtifactRuntimeConfig, ArtifactRequestHeaders } from './server/runtime-config.js';
 export { getArtifactBrowserBootstrap } from './server/request-context.js';
 export type { ArtifactRequestContext } from './server/request-context.js';
 export type { ArtifactLogMetadata, ArtifactLogRecord } from './server/logger.js';
+export type { ArtifactOrmJsonScalars } from './orm-json-scalars.js';

package/dist/server.js

@@ -1,4 +1,5 @@
 import 'server-only';
 export { createArtifactServerClient, ArtifactServerError } from './server/client.js';
+export { ARTIFACT_AUDIT_ACTIONS, ARTIFACT_AUDIT_RESOURCES_PER_EVENT, ARTIFACT_FLAGS_PER_REQUEST, ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, ARTIFACT_PROCESS_PRINCIPAL_TYPES, ARTIFACT_PROCESS_PRINCIPALS_PER_CALL, ARTIFACT_PROCESS_RUN_STATUSES, ARTIFACT_PROCESS_RUNS_LIMIT, ARTIFACT_PROCESS_TASK_VIEWS, ARTIFACT_PROCESS_TASKS_LIMIT, } from './server/broker-contract.js';
 export { getArtifactRequestContext, readArtifactRuntimeConfig } from './server/runtime-config.js';
 export { getArtifactBrowserBootstrap } from './server/request-context.js';

package/dist/source-resolver.d.ts

@@ -4,10 +4,11 @@
  * on-disk tree the rest of the pipeline (build → upload) already consumes:
  *
  *   - local folder (default, unchanged): `deploy [dir]`
- *   - a platform git-service repo:        `deploy --repo <ns>/<name> [--ref <r>]`
- *   - any external git URL:               `deploy --git-url <url> [--ref <r>]`
+ *   - a platform git-service repo:        `deploy --repo <ns>/<name> [--ref <r>] [--path <dir>]`
+ *   - any external git URL:               `deploy --git-url <url> [--ref <r>] [--path <dir>]`
  *
  * Remote sources are materialized to a temp dir and torn down after the build.
+ * `--path` selects the application directory inside a remote repository.
  */
 /** Provenance recorded on the deployment row (git_commit/git_branch/git_dirty). */
 export interface SourceProvenance {
@@ -23,14 +24,18 @@ export type SourceSpec = {
     namespace: string;
     name: string;
     ref?: string;
+    path?: string;
 } | {
     kind: 'git-url';
     url: string;
     ref?: string;
+    path?: string;
 };
 export interface ResolvedSource {
     /** Absolute, canonical (realpath'd) directory the build should run against. */
     dir: string;
+    /** `dir` relative to its repository root as a POSIX path; `.` at the root or outside Git. */
+    sourceRoot: string;
     /** True for --repo / --git-url materializations (bare tree, needs install). */
     remote: boolean;
     provenance: SourceProvenance;
@@ -67,5 +72,7 @@ export declare function resolveArtifactSource(spec: SourceSpec, opts?: {
     baseUrl?: string;
     token?: string | null;
 }): Promise<ResolvedSource>;
+/** A local source's directory relative to its Git top level, as Atlas reads it from the repository. */
+export declare function localSourceRoot(dir: string): string;
 /** Working-tree git provenance for a local source (current behavior). */
 export declare function localGitMetadata(dir: string): SourceProvenance;

package/dist/source-resolver.js

@@ -1,8 +1,8 @@
 import { execFileSync } from 'node:child_process';
 import { mkdirSync, rmSync } from 'node:fs';
-import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { mkdtemp, realpath, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve, sep } 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';
@@ -36,6 +36,14 @@ function flagString(flags, key) {
         throw new Error(`--${key} requires a value.`);
     return value;
 }
+/** A canonical relative repository directory: no absolute, empty, `.` or `..` segments. */
+function validateRepoPath(path) {
+    if (path.trim() !== path || isAbsolute(path) || path.includes('\\') ||
+        [...path].some((character) => character.charCodeAt(0) < 0x20) ||
+        path.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new Error(`--path must be a canonical relative directory within the repository (got ${JSON.stringify(path)}).`);
+    }
+}
 /**
  * Derive the source spec from parsed CLI args. Enforces mutual exclusivity:
  * a `[dir]` positional, `--repo`, and `--git-url` are three ways to name the
@@ -45,6 +53,7 @@ export function parseSourceSpec(input) {
     const repo = flagString(input.flags, 'repo');
     const gitUrl = flagString(input.flags, 'git-url');
     const ref = flagString(input.flags, 'ref');
+    const path = flagString(input.flags, 'path');
     const dir = input.positional[0];
     if (repo && gitUrl)
         throw new Error('Pass only one of --repo or --git-url.');
@@ -54,12 +63,17 @@ export function parseSourceSpec(input) {
         throw new Error('--ref only applies together with --repo or --git-url.');
     if (ref && ref.startsWith('-'))
         throw new Error(`--ref must not start with "-" (got "${ref}").`);
+    if (path !== undefined && !repo && !gitUrl)
+        throw new Error('--path only applies together with --repo or --git-url; pass a local [dir] instead.');
+    if (path !== undefined)
+        validateRepoPath(path);
+    const selection = path === undefined ? {} : { path };
     if (repo) {
         const parts = repo.split('/');
         if (parts.length !== 2 || !parts[0] || !parts[1]) {
             throw new Error(`--repo must be "<namespace>/<name>" (got "${repo}").`);
         }
-        return { kind: 'git-service', namespace: parts[0], name: parts[1], ref };
+        return { kind: 'git-service', namespace: parts[0], name: parts[1], ref, ...selection };
     }
     if (gitUrl) {
         let parsed;
@@ -76,7 +90,7 @@ export function parseSourceSpec(input) {
             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: 'git-url', url: gitUrl, ref, ...selection };
     }
     return { kind: 'local', dir: resolve(dir ?? '.') };
 }
@@ -88,7 +102,7 @@ export function parseSourceSpec(input) {
  */
 export async function resolveArtifactSource(spec, opts = {}) {
     if (spec.kind === 'local') {
-        return { dir: spec.dir, remote: false, provenance: localGitMetadata(spec.dir), cleanup: async () => { } };
+        return { dir: spec.dir, sourceRoot: localSourceRoot(spec.dir), remote: false, provenance: localGitMetadata(spec.dir), cleanup: async () => { } };
     }
     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.');
@@ -96,6 +110,9 @@ export async function resolveArtifactSource(spec, opts = {}) {
     const workspace = await makeTempDir();
     const dest = join(workspace, 'source');
     const cleanup = () => removeDir(workspace);
+    const materialized = async (provenance) => ({
+        dir: await selectRepoDir({ repoDir: dest, path: spec.path }), sourceRoot: spec.path ?? '.', remote: true, provenance, cleanup,
+    });
     try {
         if (spec.kind === 'git-service') {
             if (!opts.authMode || !opts.baseUrl || !opts.token) {
@@ -117,7 +134,7 @@ export async function resolveArtifactSource(spec, opts = {}) {
             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 };
+                return await materialized({ gitCommit: sha, gitBranch: ref, gitDirty: false });
             }
             // Human path: materialize via a smart-HTTP `git clone` (one pack
             // transfer). The earlier per-blob JSON walk was O(files) serial HTTP
@@ -129,7 +146,7 @@ export async function resolveArtifactSource(spec, opts = {}) {
                 const cloneUrl = gitServiceCloneUrl(opts.baseUrl, repo.id);
                 await runGitClone({ cloneUrl, destDir: dest, pat, ref: sha });
                 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 };
+                return await materialized({ gitCommit: sha, gitBranch: ref, gitDirty: false });
             }
             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`). ' +
@@ -137,13 +154,43 @@ export async function resolveArtifactSource(spec, opts = {}) {
         }
         const { sha, branch } = cloneGitUrl(spec.url, spec.ref, dest);
         console.log(`[seq-studio] source: ${redactGitUrl(spec.url)}${spec.ref ? `@${spec.ref}` : ''} (${sha.slice(0, 10)})`);
-        return { dir: dest, remote: true, provenance: { gitCommit: sha, gitBranch: branch, gitDirty: false }, cleanup };
+        return await materialized({ gitCommit: sha, gitBranch: branch, gitDirty: false });
     }
     catch (error) {
         await cleanup();
         throw error;
     }
 }
+/**
+ * Select `--path` inside a materialized repository. realpath containment
+ * prevents a committed symlink from escaping the checkout.
+ */
+async function selectRepoDir({ repoDir, path }) {
+    if (path === undefined)
+        return repoDir;
+    const candidate = resolve(repoDir, path);
+    const isDirectory = await stat(candidate).then((entry) => entry.isDirectory(), () => false);
+    if (!isDirectory)
+        throw new Error(`--path does not name a directory in the repository: ${path}`);
+    const [root, selected] = await Promise.all([realpath(repoDir), realpath(candidate)]);
+    const contained = relative(root, selected);
+    if (contained === '..' || contained.startsWith(`..${sep}`) || isAbsolute(contained)) {
+        throw new Error(`--path must stay within the repository: ${path}`);
+    }
+    return selected;
+}
+/** A local source's directory relative to its Git top level, as Atlas reads it from the repository. */
+export function localSourceRoot(dir) {
+    try {
+        const prefix = String(execFileSync('git', ['rev-parse', '--show-prefix'], {
+            cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        })).trim().replace(/\/$/, '');
+        return prefix || '.';
+    }
+    catch {
+        return '.';
+    }
+}
 /** Working-tree git provenance for a local source (current behavior). */
 export function localGitMetadata(dir) {
     const gitOpts = {

package/dist/templates/nextjs/AGENTS.md

@@ -0,0 +1,10 @@
+# Sequence development
+
+Before every development task, read the live documentation for this project's
+target environment. Find the environment's URL with `seq-studio envs list`
+(or the project configuration), then open `<environment-url>/docs`.
+
+Start with that site's `/docs/llms.txt` index and follow the relevant pages as
+needed. The hosted docs are the single source of truth for platform usage;
+do not duplicate their instructions in this file. If docs access is blocked,
+open the same URL in the signed-in browser.

package/dist/templates/nextjs/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/dist/templates/nextjs/README.md

@@ -77,6 +77,94 @@ platform-user relations also read `<namespace>/platformUsers`). Under
 `data.write`, use `<namespace>/ops/<Operation>` for each persisted mutation the
 app runs, or `<namespace>/<table>` for table-level coverage.
 
+To start a Lattice process, list its id under `processes.start` and call
+`processes.start({ process, runId, title, entity, metadata, assignments })`
+from a server action or route handler. The run starts as the signed-in user (or
+the attached service account, through `asService()`) and needs that identity's
+Invoker grant on the process. `runId` is an idempotency key: starting the same
+id again returns the existing run. `metadata` is the run's input
+(`ctx.run.metadata`). `assignments` names who works each human node
+(`{ execute: { groups: ['<group id>'] } }`), as `POST /api/lattice/runs` takes
+it; Atlas refuses principals it has tombstoned. The start node and version stay
+with the process.
+
+To read a process's runs, list its id under `processes.read` and call
+`processes.listRuns({ process, status, entity, limit, archived })` or
+`processes.getRun(runId)`. Both answer as `GET /api/lattice/runs` and
+`GET /api/lattice/runs/[runId]` would for the signed-in user: the list holds
+only runs that user may view, `getRun` needs Viewer on the run and returns
+`{ run, steps, states, event_cursor }`, and `run.metadata` is blank on read for
+every viewer — keep the data your pages need in your own ORM namespace. Reads
+work from pages and GET route handlers; starting a run does not.
+
+The same `processes.read` declaration lets you render the process itself.
+`processes.describe({ process, version })` returns the applied template a run
+is filled in from — `{ id, name, version, new_runs_disabled, start_node_id,
+input_schema, nodes }` — for the active version, or for a run's
+`processVersion` to show the template that run started from. Every node lists
+its `id`, `kind`, `title`, `description` and `outgoing_edges`; a `human` node
+also carries what a person working it is shown: `advance_edges`,
+`complete_label`, the author's `metadata` bag (form fields, surface hints) and
+`comments_enabled`. Automation, agent and function internals are the process's
+own and never appear. It needs Viewer on the process, which anyone who may
+start it has. `processes.listTasks({ processes, view, limit })` lists the
+signed-in user's own human steps across your declared processes (a subset, or
+all of them) — `view: 'active'` (default) for steps waiting on them,
+`'completed'` for ones they finished — each with its run and node identity plus
+the node's `title`, interpolated `description`, `advance_edges`,
+`complete_label` and `metadata`. It is always the caller's queue: there is no
+way to ask for someone else's, and nothing in a task lets you advance it
+without the user's own Lattice authority.
+
+To work those steps, list the process id under `processes.act` as well and
+call, from a server action or a non-GET route handler:
+`processes.advance({ runId, stepId, edgeId, payload })` completes one of the
+signed-in user's parked steps — `edgeId` is one of the node's `advance_edges`
+(omit it on a terminal node), `payload` is the step's output, and `stepId`
+disambiguates when a parallel block has several human branches parked. It
+needs the user's own `advancer` grant on that step: the application cannot
+complete a step as someone else. `processes.assign({ runId, stepId, users,
+groups })` reassigns a parked step (its advancers become exactly those
+principals) and `processes.grantViewers` / `processes.revokeViewers({ runId,
+users, groups })` share a run or take a share back; all three need the user to
+own the run, and `processes.listViewers(runId)` shows the run's stored shares.
+Users are Auth0 subs and groups are chat-group ids — take them from
+`processes.searchPrincipals({ q, types, limit })`, which finds people in the
+user's own tenant and groups they can see, as the Lattice picker does. The
+same applies through `asService()`: the attached service account acts under its
+own grants, with no elevation.
+
+A refused process call rejects with an `ArtifactServerError` whose `status` is
+Atlas's and whose `atlas` field keeps what Atlas said: `atlas.detail` is the
+reason, `atlas.code` the route's machine code when it has one — an advance
+answers `RUN_TERMINAL` (410) once the run has finished, `WORKFLOW_NOT_RUNNING`
+(409) while a fresh run's workflow is still being dispatched (retry shortly),
+`NO_PARKED_STEP` and `EDGE_ID_MISMATCH` (409) when the step moved on or was
+completed another way. Branch on `atlas.code`, not on the message text.
+
+Lattice calls this server only at paths listed under `server.lattice.accept`.
+Each entry is an exact origin-relative path (`/api/hooks/lattice`), with no
+wildcards. A process node names that path; the caller needs `end_user` on this
+app. The signed request context includes the Lattice run, node, step, and
+process ids.
+
+Feature flags need no declaration. `flags.isEnabled(name)` (or
+`flags.evaluate(names)` for up to 32 at once) asks Atlas, which evaluates them
+for the signed-in user as its own routes do, from any route, page or action. A
+refused call rejects, so treat a failure as off where a flag gates a change.
+
+To keep an audit trail of what users do in the application, declare
+`audit: { service: artifact_studio }` under `server.capabilities` and call
+`audit.record({ action, detail, resources, metadata })` from the server, for
+example `{ action: 'view', detail: 'invoices.view', resources: [{ type:
+'invoice', id }] }`. Atlas records it for the signed-in user, adds where it
+came from (project, deployment, request) and resolves once the audit log has it.
+Reads may record from GET handlers and pages. An application that replaces a
+product's Atlas routes can record under that product's audit service once
+Atlas registers the project for it. `metadata` takes scalars that say what
+happened, such as counts, outcomes and what was searched for. Never put request
+bodies, document contents or secrets in it.
+
 Managed secrets stay in hosted runtimes. For local integration tests, use your
 own test credentials, mocks or an existing governed function. Use a hosted
 preview for application code that needs a managed secret. Never put secrets in

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

@@ -1,90 +1,10 @@
-# Sequence Artifact Studio app
+# Sequence development
 
-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`.
+Before every development task, read the live documentation for this project's
+target environment. Find the environment's URL with `seq-studio envs list`
+(or the project configuration), then open `<environment-url>/docs`.
 
-## 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 the CLI-pinned SDK, whose `seq` export uses the host-injected `window.seq`. The SDK also provides `createArtifactOrmExecutor({ namespace, manifest })` for persisted ORM operations; declare `/api/data/v2/<namespace>` under `capabilities.api.write`, including queries (execution uses POST). The helper handles the ORM envelope; do not pass its result to the CRM `unwrap()` helper. 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 + canonical `@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`, `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).
+Start with that site's `/docs/llms.txt` index and follow the relevant pages as
+needed. The hosted docs are the single source of truth for platform usage;
+do not duplicate their instructions in this file. If docs access is blocked,
+open the same URL in the signed-in browser.

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

@@ -1,7 +1 @@
-# Sequence Artifact Studio app
-
-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.
-
 @AGENTS.md

package/dist/templates/react-vite/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@sequenceholdings/artifact-studio": "^0.4.0",
+    "@sequenceholdings/artifact-studio": "^0.5.0",
     "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",

package/dist/templates/react-vite/src/App.tsx

@@ -1,3 +1,4 @@
+import { useState } from 'react'
 import { seq } from '@sequenceholdings/artifact-studio'
 import {
   Button,
@@ -15,23 +16,36 @@ const CARDS = [
 ]
 
 export default function App() {
+  const [status, setStatus] = useState<'idle' | 'pending' | 'ok' | 'error'>('idle')
+
   async function pingAtlas() {
-    const response = await seq.api.get<{ ok?: boolean }>('/api/health')
-    alert(`Atlas responded: ${JSON.stringify(response)}`)
+    setStatus('pending')
+    try {
+      await seq.api.get<{ ok?: boolean }>('/api/health')
+      setStatus('ok')
+    } catch {
+      setStatus('error')
+    }
   }
 
   return (
-    <main className="min-h-screen bg-background p-10">
-      <p className="text-xs font-extrabold tracking-widest uppercase text-primary mb-2">
-        Artifact Studio
-      </p>
-      <h1 className="text-lg font-bold tracking-tight">Build on Atlas</h1>
-      <p className="text-muted-foreground leading-relaxed max-w-2xl mt-2">
-        This app uses Atlas&apos;s shared UI component library. Import any
-        component from <code className="text-sm font-mono">@sequenceholdings/atlas-ui</code>.
+    <main className="min-h-full bg-background p-roomy text-foreground sm:p-10">
+      <div>
+        <p className="mb-2 text-xs font-extrabold uppercase tracking-widest text-primary">
+          Artifact Studio
+        </p>
+        <h1 className="text-lg font-bold tracking-tight">Build on Atlas</h1>
+      </div>
+      <p className="mt-2 max-w-2xl leading-relaxed text-muted-foreground">
+        This app uses Atlas&apos;s shared UI component library. Import any component
+        from{' '}
+        <code className="font-mono text-sm">
+          @sequenceholdings/atlas-ui
+        </code>
+        .
       </p>
 
-      <div className="grid grid-cols-1 sm:grid-cols-3 gap-sm mt-7 max-w-3xl">
+      <div className="mt-7 grid max-w-3xl grid-cols-1 gap-inline-loose sm:grid-cols-3">
         {CARDS.map((card) => (
           <Card key={card.label}>
             <CardHeader>
@@ -46,9 +60,18 @@ export default function App() {
         ))}
       </div>
 
-      <Button className="mt-6" onClick={pingAtlas}>
-        Test Atlas API bridge
-      </Button>
+      <div className="mt-6 flex flex-wrap items-center gap-inline">
+        <Button
+          size="lg"
+          className="min-h-11"
+          disabled={status === 'pending'}
+          onClick={() => void pingAtlas()}
+        >
+          {status === 'pending' ? 'Testing…' : 'Test Atlas API bridge'}
+        </Button>
+        {status === 'ok' ? <Badge variant="secondary">Atlas responded</Badge> : null}
+        {status === 'error' ? <Badge variant="destructive">Request failed</Badge> : null}
+      </div>
     </main>
   )
 }

package/dist/templates/react-vite/src/styles.css

@@ -10,3 +10,13 @@
    build-time injection. At DES-227 cutover, tokens.css becomes v2 — drop the
    explicit tokens.v2 / theme.v2 imports (and the CLI stops injecting them). */
 @source "../node_modules/@sequenceholdings/atlas-ui/dist";
+
+html,
+body,
+#root {
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+}

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "SDK types and CLI library for building Artifact Studio apps. Driven via `seq-studio artifact <sub>` (@sequenceholdings/studio-cli), which runs the `./cli` runCli export.",
   "type": "module",
   "exports": {
@@ -17,6 +17,10 @@
       "types": "./dist/sdk.d.ts",
       "default": "./dist/sdk.js"
     },
+    "./offline": {
+      "types": "./dist/offline/index.d.ts",
+      "default": "./dist/offline/index.js"
+    },
     "./cli": {
       "types": "./dist/cli.d.ts",
       "default": "./dist/cli.js"
@@ -146,9 +150,9 @@
     "google-auth-library": "^10.5.0",
     "server-only": "0.0.1",
     "parse5": "7.3.0",
-    "@sequenceholdings/lattice-form-renderer": "0.1.3",
     "@sequenceholdings/storage": "0.1.0",
-    "@sequenceholdings/orm": "2.1.1"
+    "@sequenceholdings/orm": "2.2.0",
+    "@sequenceholdings/lattice-form-renderer": "0.2.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/templates/nextjs/AGENTS.md

@@ -0,0 +1,10 @@
+# Sequence development
+
+Before every development task, read the live documentation for this project's
+target environment. Find the environment's URL with `seq-studio envs list`
+(or the project configuration), then open `<environment-url>/docs`.
+
+Start with that site's `/docs/llms.txt` index and follow the relevant pages as
+needed. The hosted docs are the single source of truth for platform usage;
+do not duplicate their instructions in this file. If docs access is blocked,
+open the same URL in the signed-in browser.

package/templates/nextjs/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md