@sequenceholdings/artifact-studio 0.4.0 → 0.6.1

package/dist/server/testing.d.ts

@@ -0,0 +1,40 @@
+import { type KeyObject } from 'node:crypto';
+import { type RequestContextV2External } from './request-context.js';
+import { type ArtifactRuntimeConfig } from './runtime-config.js';
+/**
+ * Test helpers for applications that accept external callers: sign an external (v2) context
+ * with a test key, and run code against an explicit runtime configuration. For unit tests and
+ * local `next dev` only. A context signed here verifies only against the matching public key,
+ * which a hosted runtime never pins.
+ */
+type ExternalPrincipalClaims = RequestContextV2External['principal'];
+export interface SignTestExternalContextInput {
+    privateKey: KeyObject | string;
+    /** Use an `external-` kid; verifiers refuse any other kid on an external context. */
+    kid: string;
+    projectId: string;
+    environment: string;
+    method: string;
+    path: string;
+    /** Overrides on a verified-borrower default principal. */
+    principal?: Partial<Omit<ExternalPrincipalClaims, 'kind'>>;
+    serviceAccountId: string;
+    /** Defaults to `published`. Verifiers refuse `development` until development leases admit it. */
+    mode?: RequestContextV2External['mode'];
+    deploymentId?: string | null;
+    devSessionId?: string | null;
+    /** Seconds since the epoch; defaults to now. */
+    now?: number;
+    /** Defaults to and may not exceed 60. */
+    ttlSeconds?: number;
+    /** Overrides applied after the defaults, unvalidated, for negative tests. */
+    claims?: Record<string, unknown>;
+}
+export declare function signTestExternalContext({ privateKey, kid, projectId, environment, method, path, principal, serviceAccountId, mode, deploymentId, devSessionId, now, ttlSeconds, claims, }: SignTestExternalContextInput): string;
+/**
+ * Runs `fn` with the hosted runtime configuration set to `config` (and no runtime file), then
+ * restores the previous environment. The override is process-wide: do not run overlapping calls.
+ * Refuses to run in a production build.
+ */
+export declare function withTestRuntimeConfig<T>(config: ArtifactRuntimeConfig, fn: () => Promise<T> | T): Promise<T>;
+export {};

package/dist/server/testing.js

@@ -0,0 +1,86 @@
+import { createHash, createPrivateKey, randomUUID, sign } from 'node:crypto';
+import { ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS, requestContextV2ExternalSchema } from './request-context.js';
+import { artifactRuntimeConfigSchema } from './runtime-config.js';
+const defaultUserAgent = 'Mozilla/5.0 (test)';
+export function signTestExternalContext({ privateKey, kid, projectId, environment, method, path, principal = {}, serviceAccountId, mode = 'published', deploymentId, devSessionId, now = Math.floor(Date.now() / 1000), ttlSeconds = ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS, claims = {}, }) {
+    const userAgent = principal.client?.userAgent ?? defaultUserAgent;
+    const resolvedPrincipal = {
+        kind: 'external',
+        ingress: 'borrower',
+        provider: 'test-provider',
+        issuer: 'https://idp.example.test/',
+        subject: 'test|borrower-1',
+        clientId: 'test-client',
+        email: 'borrower@example.test',
+        emailVerified: true,
+        authTime: now - 30,
+        amr: ['pwd'],
+        tokenIssuedAt: now - 30,
+        ...principal,
+        pass: { id: randomUUID(), kid: 'pass-1', issuedAt: now - 10, exchangeIp: '203.0.113.10', ...principal.pass },
+        client: {
+            ip: '203.0.113.10',
+            userAgentSha256: createHash('sha256').update(userAgent).digest('hex'),
+            origin: 'https://borrower.example.test',
+            ...principal.client,
+            userAgent,
+        },
+    };
+    const published = mode === 'published';
+    const payload = {
+        v: 2,
+        iss: 'atlas-artifact-gateway',
+        aud: `artifact:${projectId}`,
+        sub: `ext|${resolvedPrincipal.provider}|${resolvedPrincipal.subject}`,
+        projectId,
+        environment,
+        mode,
+        deploymentId: deploymentId !== undefined ? deploymentId : published ? 'test-deployment' : null,
+        devSessionId: devSessionId !== undefined ? devSessionId : published ? null : 'test-dev-session',
+        requestId: randomUUID(),
+        jti: randomUUID(),
+        method: method.toUpperCase(),
+        path,
+        iat: now,
+        exp: now + ttlSeconds,
+        serviceAccountId,
+        principal: resolvedPrincipal,
+        crit: [],
+        ext: {},
+        ...claims,
+    };
+    // Catch a mistaken default early; `claims` overrides are for deliberately invalid contexts.
+    if (Object.keys(claims).length === 0)
+        requestContextV2ExternalSchema.parse(payload);
+    const key = typeof privateKey === 'string' ? createPrivateKey(privateKey) : privateKey;
+    const unsigned = [{ alg: 'EdDSA', typ: 'JWT', kid }, payload]
+        .map(part => Buffer.from(JSON.stringify(part)).toString('base64url')).join('.');
+    return `${unsigned}.${sign(null, Buffer.from(unsigned), key).toString('base64url')}`;
+}
+const runtimeEnvironmentKeys = ['SEQUENCE_ARTIFACT_RUNTIME_FILE', 'SEQUENCE_ARTIFACT_RUNTIME_CONFIG', 'SEQUENCE_ARTIFACT_RUNTIME_TOKEN'];
+/**
+ * Runs `fn` with the hosted runtime configuration set to `config` (and no runtime file), then
+ * restores the previous environment. The override is process-wide: do not run overlapping calls.
+ * Refuses to run in a production build.
+ */
+export async function withTestRuntimeConfig(config, fn) {
+    if (process.env.NODE_ENV === 'production')
+        throw new Error('withTestRuntimeConfig is for tests and local development only');
+    const { sessionToken, ...hosted } = artifactRuntimeConfigSchema.parse(config);
+    const previous = Object.fromEntries(runtimeEnvironmentKeys.map(key => [key, process.env[key]]));
+    delete process.env.SEQUENCE_ARTIFACT_RUNTIME_FILE;
+    process.env.SEQUENCE_ARTIFACT_RUNTIME_CONFIG = JSON.stringify(hosted);
+    process.env.SEQUENCE_ARTIFACT_RUNTIME_TOKEN = sessionToken;
+    try {
+        return await fn();
+    }
+    finally {
+        for (const key of runtimeEnvironmentKeys) {
+            const value = previous[key];
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+    }
+}

package/dist/server.d.ts

@@ -1,8 +1,17 @@
 import 'server-only';
-export { createArtifactServerClient, ArtifactServerError } from './server/client.js';
-export type { ArtifactOrmOperations, ArtifactServerClient, ArtifactServerFetchOptions } from './server/client.js';
+export { createArtifactServerClient } from './server/client.js';
+export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './server/errors.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, ArtifactServerClientOptions, ArtifactServerContext, 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 { ArtifactContextError, getArtifactBrowserBootstrap } from './server/request-context.js';
+export type { ArtifactContextErrorReason, ArtifactRequestContext, RequestContextV2External } from './server/request-context.js';
+export { verifyArtifactExternalContext } from './server/external-context.js';
+export type { ArtifactExternalAccept } from './server/external-context.js';
+export { externalEvidence } from './server/principal.js';
+export type { ArtifactExternalEvidence, ArtifactExternalPrincipal, ArtifactPrincipal } from './server/principal.js';
 export type { ArtifactLogMetadata, ArtifactLogRecord } from './server/logger.js';
+export type { ArtifactOrmJsonScalars } from './orm-json-scalars.js';

package/dist/server.js

@@ -1,4 +1,8 @@
 import 'server-only';
-export { createArtifactServerClient, ArtifactServerError } from './server/client.js';
+export { createArtifactServerClient } from './server/client.js';
+export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './server/errors.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';
+export { ArtifactContextError, getArtifactBrowserBootstrap } from './server/request-context.js';
+export { verifyArtifactExternalContext } from './server/external-context.js';
+export { externalEvidence } from './server/principal.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/nextjs/package.json

@@ -10,7 +10,9 @@
     "dev": "next dev --webpack --hostname 127.0.0.1",
     "build": "next build",
     "start": "next start --hostname 127.0.0.1",
-    "type-check": "next typegen && tsc --noEmit"
+    "lint": "next typegen && tsc --noEmit --noUnusedLocals --noUnusedParameters --noFallthroughCasesInSwitch",
+    "type-check": "next typegen && tsc --noEmit",
+    "test": "node --test tests/*.test.mjs"
   },
   "dependencies": {
     "@sequenceholdings/artifact-studio": "{{artifactStudioVersion}}",

package/dist/templates/nextjs/tests/server.test.mjs

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { greet } from '../app/actions.ts'
+import { GET } from '../app/api/health/route.ts'
+
+test('greeting validates input and returns the server action result', async () => {
+  const data = new FormData()
+  data.set('name', '  Atlas  ')
+  assert.deepEqual(await greet({ message: '', error: null }, data), {
+    message: 'Hello, Atlas. Your server action ran successfully.', error: null,
+  })
+  for (const name of ['', ' '.repeat(3), 'a'.repeat(81)]) {
+    data.set('name', name)
+    const result = await greet({ message: '', error: null }, data)
+    assert.equal(result.message, '')
+    assert.equal(result.error, 'Enter a name between 1 and 80 characters.')
+  }
+})
+
+test('health route returns uncached JSON without any runtime bindings', async () => {
+  const response = GET()
+  assert.equal(response.status, 200)
+  assert.equal(response.headers.get('cache-control'), 'no-store')
+  assert.deepEqual(await response.json(), { ok: true, framework: 'nextjs' })
+})

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.6.0",
     "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",