@sequenceholdings/studio-cli 0.1.24 → 0.1.26

package/README.md

@@ -150,14 +150,19 @@ without it.
 
 | Command | What it does |
 |---------|--------------|
-| `seq-studio init <dir> --with <kinds>` | Scaffold an app monorepo + `sequence.app.yml` + selected primitive subfolders |
+| `seq-studio init <dir> --with <kinds>` | Scaffold an app monorepo + `sequence.app.yml` + a Sequence app `README.md` + selected primitive subfolders |
 | `seq-studio add function&#124;artifact <name>` | Add a function or Artifact Studio UI to the current app (updates the manifest) |
 | `seq-studio deploy -e <env> [--yes] [--only id1,id2] [--dry-run]` | Deploy every primitive in `deploy.order` (orm → functions → artifact) |
 
 `init` supports v0 kinds `orm`, `function`, and `artifact`; pass them as a
 comma-list (`--with orm,function,artifact`) or boolean flags (`--orm`). `add`
 currently supports functions and one Artifact Studio UI; ORM is created only by
-`init`.
+`init`. Creating a platform git-service repo (`seq-studio repos create` or the
+Repositories UI) writes the same class of README into the initial commit, so a
+fresh clone already has the primitives / [docs.seqholdings.com](https://docs.seqholdings.com/)
+guide. `seq-studio init .` is allowed in a clone whose README contains the
+seq-studio seed marker; it merges Sequence ignores into an existing
+`.gitignore` and will not overwrite an ordinary docs-only README.
 
 ```bash
 # Full-stack toy (ORM + function + artifact) — workspace / internal CLI only
@@ -405,6 +410,27 @@ limits:
 `min_instances` defaults to `0`, cannot exceed `max_instances`, and incurs
 Cloud Run idle-instance charges while warm.
 
+### Invocation IP allowlist
+
+Declare the function-level source-IP restriction in `managed-function.yml`:
+
+```yaml
+invocation:
+  allowed_ip_ranges:
+    - 203.0.113.0/24
+    - 2001:db8::/48
+```
+
+`seq-studio functions build` validates IPv4/IPv6 addresses and CIDRs locally;
+Atlas performs authoritative normalization during upload. `/0` ranges are
+rejected. Omitting `invocation` or declaring `allowed_ip_ranges: []` means
+unrestricted source IPs.
+
+The policy is part of the immutable function version. It becomes live atomically
+when that version activates, a failed deploy leaves the current policy unchanged,
+and promote or rollback restores the selected version's policy. The gateway
+checks a non-empty policy before invocation permissions.
+
 ### Server-owned resource authorization
 
 Some functions expose regulated external resources whose authorization must be
@@ -588,7 +614,7 @@ JSON API — the same repos `--repo <ns>/<name>` sources build from.
 | `seq-studio repos list -e <env> [--namespace <slug>] [--mine]` | repos visible on the environment (permission-filtered) |
 | `seq-studio repos namespaces [create <slug>] -e <env>` | list namespaces, or create one (creator becomes owner) |
 | `seq-studio repos show <ns>/<name> -e <env>` | detail: id, branches, clone URL; artifact project id when slug matches |
-| `seq-studio repos create <ns>/<name> -e <env> [--default-branch <b>]` | create an empty repo (needs namespace write) |
+| `seq-studio repos create <ns>/<name> -e <env> [--default-branch <b>]` | create a repo seeded with a Sequence app README (needs namespace write) |
 | `seq-studio repos clone <ns>/<name> \| --url <clone-url> \| --id <uuid> -e <env> [--ref <r>] [--out <dir>] [--force]` | smart-HTTP `git clone` when `ATLAS_GIT_PAT` is set (`--url`/`--id` need no seqapi); otherwise JSON materialize + PAT hint |
 | `seq-studio repos pull <ns>/<name> -e <env> [--ref <r>] [--out <dir>] [--force]` | always materialize via JSON API (no `.git` dir); refuses a non-empty destination unless `--force` |
 | `seq-studio repos delete <ns>/<name> -e <env> [--yes]` | delete a repo — interactive confirm unless `--yes` |
@@ -632,8 +658,8 @@ install it alongside the CLI to use this family.
 |---------|--------------|
 | `seq-studio pipeline init --type ingestion\|transformation\|serving <name> [--dir <dir>]` | Scaffold `<name>.stage.yml` (commented per-kind template) plus a `src/` Databricks-notebook entrypoint stub (begins with `# Databricks notebook source`; serving stages are declarative — no stub). Refuses to overwrite an existing spec |
 | `seq-studio pipeline validate [dir] [--assets <file\|url>] [--orm-contracts <file\|url>] [--json]` | Run the full offline spec gate: envelope + body validation, `schema_ref` resolution, and repo-level graph validation (reference resolution, single-writer, cycles, column subsets, serving projection checks). Auto-loads `orm-contracts.json` from the pipeline dir when present. Exit 0/1 |
-| `seq-studio pipeline plan --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--json]` | Plan a Pipeline deploy (materialize → SDK/`validateSpecGraph` → compile → live-diff → provision findings). Fails closed listing **every** missing target binding (alert channels, workspace, Databricks `source.credential`) plus Data Sync edge-worker machine/operation/`credEnvFamilies` mismatches before registry writes. Does **not** run Databricks `bundle validate` (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). `--json` emits the stable plan envelope |
-| `seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--approved-by <sub>] [--no-wait]` | Plan then enqueue deploy; Trigger runs `bundle validate` then `bundle deploy` against reviewed bytes. Polls to terminal unless `--no-wait`. Targets that require approval need `--approved-by` naming the authenticated caller. |
+| `seq-studio pipeline plan --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--json]` | Enqueue and poll a durable Pipeline plan (materialize → SDK/`validateSpecGraph` → compile → live-diff → provision findings). Fails closed listing **every** missing target binding (alert channels, workspace, Databricks `source.credential`) plus Data Sync edge-worker machine/operation/`credEnvFamilies` mismatches before registry writes. Does **not** run Databricks `bundle validate` (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). `--json` emits the completed stable plan envelope |
+| `seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--approved-by <sub>] [--run-now] [--no-wait]` | Plan then enqueue deploy; Trigger runs `bundle validate` then `bundle deploy` against reviewed bytes. Default is plant-only (jobs are created, not run). `--run-now` runs in-unit producer roots after bundle deploy and waits before serving sync create. Polls to terminal unless `--no-wait`. Targets that require approval need `--approved-by` naming the authenticated caller. |
 | `seq-studio pipeline adopt --stage <slug> --ref <sha\|branch> -e <env> [--target <id>] --native-id <id> --approved-by <you> [--resource-key <key>] [--kind job\|dlt_pipeline] [--old-source-removal-pr <url>] [--repo pipelines/<slug>]` | Bind a live Databricks job/pipeline into the stage without recreation (`bundle deployment bind` on Trigger). Always requires `--approved-by` naming the caller. When the key is still in the monorepo DAB, pass `--old-source-removal-pr` and follow the returned cutover checklist: unbind the old bundle state without deleting the remote, then remove its DAB declaration and add the target-specific adopted-resource entry in the same PR before redeploying. |
 | `seq-studio pipeline unbind --stage <slug> --ref <sha\|branch> -e <env> [--target <id>] --approved-by <you> [--resource-key <key>] [--repo pipelines/<slug>]` | Release an adopted binding on Trigger; the remote object stays live (never deleted) |
 | `seq-studio pipeline run-now --stage <slug> -e <env> [--target <id>] [--repo pipelines/<slug>] [--json]` | Run the stage's active job or DLT pipeline immediately and print its Databricks run URL |
@@ -644,7 +670,7 @@ install it alongside the CLI to use this family.
 pipeline target advertised by that endpoint. It is optional when the alias
 matches a target id or when the endpoint has exactly one target.
 
-Unless `--no-wait` is set, `deploy`, `promote`, and `rollback` report status or
+Unless `--no-wait` is set, `plan`, `deploy`, `promote`, and `rollback` report status or
 status-detail changes while waiting, then emit a 20-second progress heartbeat.
 Terminal output includes the deployment ID and elapsed time; failures include
 the status detail, and any available Trigger run ID is shown. `--json` output

package/dist/app/commands.js

@@ -15,8 +15,11 @@ export const APP_INIT_USAGE = `usage:
   seq-studio init <dir> --with <kinds> [options]
   seq-studio init <dir> --orm --function --artifact [options]
 
-  Scaffold an app monorepo with ${APP_MANIFEST_FILENAME} and one subfolder per
-  selected primitive. At least one kind is required.
+  Scaffold an app monorepo with ${APP_MANIFEST_FILENAME}, a Sequence app
+  README.md (docs.seqholdings.com + primitives), and one subfolder per
+  selected primitive. At least one kind is required. A git-service clone
+  whose README.md contains the seq-studio seed marker is a valid target;
+  ordinary docs-only repositories are refused so we do not overwrite them.
 
   Kinds: ${PRIMITIVE_KINDS.join(', ')}
 

package/dist/app/readme.d.ts

@@ -0,0 +1,33 @@
+/**
+ * README seeded by `seq-studio init` (and kept equivalent to the git-service
+ * createRepo initial commit). Third-party developers should be able to clone
+ * a new app repo and start building on Artifact Studio, the ORM, and
+ * Managed Functions without guessing the platform model.
+ *
+ * Keep in sync with atlas/src/server/services/git-service/initial-readme.ts.
+ */
+import type { PrimitiveKind } from './manifest.js';
+export declare const SEQUENCE_DOCS_URL = "https://docs.seqholdings.com/";
+/**
+ * Hidden marker written into the git-service createRepo README.
+ * `seq-studio init .` only overwrites a non-empty target when this is present,
+ * so an ordinary docs-only repository is not treated as a seed clone.
+ *
+ * Keep identical to atlas/src/server/services/git-service/initial-readme.ts.
+ */
+export declare const GIT_SERVICE_SEED_MARKER = "<!-- seq-studio:git-service-seed -->";
+export declare function isGitServiceSeedReadme(body: string): boolean;
+export declare const README_REQUIRED_SECTIONS: readonly ["https://docs.seqholdings.com/", "Artifact Studio", "ORM", "Managed Function", "seq-studio init", "seq.functions.invoke"];
+export interface AppReadmeInput {
+    appId: string;
+    title?: string;
+    description?: string;
+    primitives: readonly PrimitiveKind[];
+    functionName?: string;
+}
+export declare function renderAppReadme(input: AppReadmeInput): string;
+/** README for a brand-new git-service repo that does not yet have an app scaffold. */
+export declare function renderEmptyRepoReadme({ repoName, namespaceSlug, }: {
+    repoName: string;
+    namespaceSlug?: string;
+}): string;

package/dist/app/readme.js

@@ -0,0 +1,294 @@
+/**
+ * README seeded by `seq-studio init` (and kept equivalent to the git-service
+ * createRepo initial commit). Third-party developers should be able to clone
+ * a new app repo and start building on Artifact Studio, the ORM, and
+ * Managed Functions without guessing the platform model.
+ *
+ * Keep in sync with atlas/src/server/services/git-service/initial-readme.ts.
+ */
+import { titleizeSlug } from './manifest.js';
+export const SEQUENCE_DOCS_URL = 'https://docs.seqholdings.com/';
+/**
+ * Hidden marker written into the git-service createRepo README.
+ * `seq-studio init .` only overwrites a non-empty target when this is present,
+ * so an ordinary docs-only repository is not treated as a seed clone.
+ *
+ * Keep identical to atlas/src/server/services/git-service/initial-readme.ts.
+ */
+export const GIT_SERVICE_SEED_MARKER = '<!-- seq-studio:git-service-seed -->';
+export function isGitServiceSeedReadme(body) {
+    return body.includes(GIT_SERVICE_SEED_MARKER);
+}
+export const README_REQUIRED_SECTIONS = [
+    'https://docs.seqholdings.com/',
+    'Artifact Studio',
+    'ORM',
+    'Managed Function',
+    'seq-studio init',
+    'seq.functions.invoke',
+];
+export function renderAppReadme(input) {
+    const title = input.title?.trim() || titleizeSlug(input.appId);
+    const description = input.description?.trim() ||
+        'A Sequence Platform app. Keep source in Git and deploy with seq-studio.';
+    const kinds = new Set(input.primitives);
+    const functionName = input.functionName ?? 'hello';
+    const tree = renderAppTree({
+        appId: input.appId,
+        kinds,
+        functionName,
+    });
+    const primitiveRows = [
+        kinds.has('artifact')
+            ? '| **Artifact Studio** | Frontend | `artifact/` — React UI + `artifact.bundle.yml` |'
+            : null,
+        kinds.has('orm')
+            ? `| **ORM** | Data | \`orm/${snake(input.appId)}/\` — tables, policies, named GraphQL operations |`
+            : null,
+        kinds.has('function')
+            ? `| **Managed Function** | Backend | \`functions/${functionName}/\` — TypeScript handler + \`managed-function.yml\` |`
+            : null,
+    ]
+        .filter((row) => row !== null)
+        .join('\n');
+    return `# ${title}
+
+${description}
+
+This folder is a **seq-studio app**. You keep source in Git (this repository, or a platform git-service clone). You validate, plan, and deploy with \`seq-studio\`. You do not need a checkout of Sequence Platform itself.
+
+**Platform documentation:** [${SEQUENCE_DOCS_URL}](${SEQUENCE_DOCS_URL})
+
+You still need an environment name, an Atlas URL, and resource grants from your platform administrator before Preview or deploy. Login proves identity; it does not grant every action.
+
+## What this repository is
+
+A Sequence app is a folder with a \`sequence.app.yml\` manifest plus one subdirectory per platform primitive. The CLI owns that manifest (\`seq-studio init\` / \`seq-studio add\`). Do not invent a new layout by hand.
+
+\`\`\`
+${tree}
+\`\`\`
+
+This app currently includes:
+
+| Primitive | Role | Where it lives |
+| --- | --- | --- |
+${primitiveRows}
+
+Add another function later with \`seq-studio add function <name>\` from this directory. \`seq-studio add\` supports \`function\` and \`artifact\` only — an ORM namespace is created at init.
+
+## Platform primitives
+
+Build each app from these three primitives. Use only the ones the product needs.
+
+| Primitive | Role | What you write | What the platform runs |
+| --- | --- | --- | --- |
+| **Artifact Studio** | Frontend | React UI + \`artifact.bundle.yml\` | Sandboxed browser app inside Atlas |
+| **ORM** | Data | TypeScript tables, row policies, named GraphQL operations | Governed Data API in front of Postgres (you never open a connection) |
+| **Managed Function** | Backend | TypeScript handler + \`managed-function.yml\` | Server-side code with declared secrets, egress, and invoke permissions |
+
+\`\`\`
+Browser user
+    │
+    ▼
+Artifact Studio UI
+    │   seq.api.* / seq.functions.invoke  (declared capabilities only)
+    ├──► ORM Data API          persisted rows, policy-scoped to the caller
+    └──► Managed Function      secrets, egress, work that must not run in the browser
+\`\`\`
+
+**Artifact Studio** is the screen. In Atlas the UI runs in a sandboxed iframe and talks to the platform through \`seq\` from \`@sequenceholdings/artifact-studio\`. It has no raw network access and must not contain secrets. Every table, operation, API path, or function the UI uses must be listed in \`artifact.bundle.yml\` first. Prefer \`@sequenceholdings/atlas-ui\`. Docs: [Artifact Studio](${SEQUENCE_DOCS_URL}artifact-studio/overview).
+
+**ORM** is the data layer. You author tables and policies in TypeScript (\`defineNamespace\`, \`defineTable\`) and persist reads/writes as named GraphQL documents. \`seq-studio orm apply\` compiles that into a reviewed migration and publishes persisted operations. The UI calls \`{ op: <hash>, variables }\` on the Atlas Data API. Policies are the row boundary — stamp identity from \`claim('sub')\` rather than trusting the browser. There is no ad-hoc SQL; exotic writes go through a declared table action. Public docs do not yet have an ORM guide; \`seq-studio orm --help\` and a reference app (for example Pokedex: Artifact UI + trainer-scoped \`pokemon\` rows) are the working model.
+
+**Managed Function** is the backend. Use it for an external API, a write-only secret, or any work that must not run in the browser. The handler receives JSON and returns JSON. The manifest declares secret *names* (never values) and an egress allowlist — functions do not get arbitrary outbound network. Docs: [Managed Functions](${SEQUENCE_DOCS_URL}managed-functions/overview), [Managed Secrets](${SEQUENCE_DOCS_URL}managed-secrets/overview).
+
+How the examples split:
+
+| Example | Primitives | Use it for |
+| --- | --- | --- |
+| Pokedex-style app | Artifact + ORM | UI that reads and writes governed tables |
+| [Basketball player lookup](${SEQUENCE_DOCS_URL}examples/basketball-player-lookup) | Artifact + Function + Secret | UI that calls protected server-side code |
+| \`seq-studio init --with orm,function,artifact\` | All three | The intended app shape, once the ORM package is available (see below) |
+
+A function calling the ORM under a service account is **not** a supported public path yet. Keep user-scoped table access in the artifact; keep secrets and egress in the function.
+
+The public [CLI command reference](${SEQUENCE_DOCS_URL}seq-studio/commands) covers standalone \`artifact\` / \`functions\` / \`secrets\` commands. App-monorepo verbs (\`init\`, \`add\`, \`deploy\`) and \`orm\` are on \`seq-studio --help\`. Prefer \`--help\` when the two disagree.
+
+## Before you write code
+
+Ask your administrator for:
+
+1. **Environment name** — the exact \`-e\` / \`--env\` value. Do not invent it from this repository name.
+2. **Atlas URL** — the origin used with \`seq-studio envs add\`. It is not docs.seqholdings.com. The CLI discovers login config at \`{url}/api/auth/cli-config\`.
+3. **What you should create** — new Artifact Studio project, new function, new ORM namespace, or updates to existing ones.
+4. **Grants** — create/deploy an artifact; runtime access to open the deployed UI; create/deploy/invoke a function; create secrets if you need them; apply an ORM namespace if you will persist data; permission to **share** the artifact (scaffolds create \`visibility: private\`, and a later deploy will not change that).
+5. **\`@sequenceholdings/orm\` v2** — \`seq-studio init --with orm\` and namespace \`package.json\` files depend on \`@sequenceholdings/orm@^2.0.0\`, which is **not published**. Public npm's latest is a v1 package. Without a v2 tarball you can still ship Artifact + Function apps.
+
+\`local\`, \`staging\`, \`production\`, and \`banksouth\` are **reserved built-in CLI names**. \`seq-studio envs add banksouth …\` fails. Use the OpCo name you were given.
+
+See [Before you build](${SEQUENCE_DOCS_URL}getting-started/understand-your-workspace).
+
+## Install and sign in
+
+| Tool | Requirement |
+| --- | --- |
+| Node.js | 20 or later (22 is the documented baseline) |
+| pnpm | 10.28.2 |
+| Git | Required for official Artifact Studio deploys |
+| \`seq-studio\` | \`@sequenceholdings/studio-cli\` (match \`studio.min_cli\` in \`sequence.app.yml\`) |
+
+\`\`\`bash
+corepack enable
+corepack prepare pnpm@10.28.2 --activate
+pnpm setup          # once; restart the terminal afterwards
+pnpm add -g @sequenceholdings/studio-cli
+seq-studio version
+
+seq-studio envs add <environment-name> <atlas-url>
+seq-studio login --env <environment-name>
+seq-studio artifact list -e <environment-name>
+seq-studio functions list -e <environment-name>
+seq-studio doctor -e <environment-name>
+\`\`\`
+
+Details: [Install seq-studio](${SEQUENCE_DOCS_URL}getting-started/prerequisites), [Authenticate](${SEQUENCE_DOCS_URL}getting-started/authentication).
+
+\`local\` (\`http://localhost:5001\`) is a real Atlas process, not Vite. After init the CLI may print \`seq-studio deploy -e local --yes\` — ignore that unless you actually run Atlas locally.
+
+## Implement this app
+
+${renderImplementSection({ kinds, functionName, appId: input.appId })}
+
+## Everyday loop
+
+| You want to… | Command |
+| --- | --- |
+| Validate / build an artifact | \`seq-studio artifact validate artifact\` / \`artifact build artifact\` |
+| Preview uncommitted UI | \`seq-studio artifact dev artifact -e <env>\` |
+| Official UI deploy | \`seq-studio artifact deploy artifact -e <env>\` from clean \`main\` |
+| Build / deploy a function | \`seq-studio functions build --dir functions/<name>\` then \`functions deploy --dir … -e <env>\` |
+| Function logs | \`seq-studio functions logs --fn <slug> -e <env>\` |
+| Apply an ORM namespace | \`seq-studio orm apply orm/<namespace> -e <env>\` |
+| Deploy every primitive | \`seq-studio deploy -e <env>\` from this directory |
+
+Official Artifact Studio deploys require a **clean \`main\`** with a committed revision. Uncommitted work is Preview (\`artifact dev\`). Open the URL the CLI prints.
+
+## Rules that waste a day if you skip them
+
+- **Manifests are the authorization surface.** A new \`seq.api\` call, ORM mutation, secret, or outbound host in source is not enough. Update \`artifact.bundle.yml\` or \`managed-function.yml\` and validate again.
+- **Never commit secret values.** \`.env\` is gitignored. Never put secrets in the artifact — that bundle is browser code.
+- **Delete the Chainguard \`.npmrc\`** in a new function unless you have Sequence-internal registry credentials. Without them \`pnpm install\` 401s. Removing the file is the supported public path.
+- **Invoke functions with \`seq.functions.invoke('<slug>', body)\`**, not a raw \`seq.api.post\` to \`/api/managed-functions/…\`. Declare the slug under \`capabilities.functions.invoke\`.
+- **Atlas wraps many \`seq.api\` responses** as \`{ success, data }\`. Use the scaffold \`unwrap\` helper. \`seq.functions.invoke\` is already the payload.
+- **Do not reuse another app's identities.** If you copy files, change \`app.id\`, every primitive \`id\`, the ORM \`namespace\`, the artifact \`project_id\`, capability paths, and \`targets\`.
+- **Do not edit ORM \`migrations/\`.** Change \`schema/*.ts\` / \`graphql/**/*.ts\`, then generate/apply.
+- **Do not hardcode user emails** in policies or UI. Use \`claim('sub')\` / \`claim('org')\` and the Permissions / sharing UI.
+
+## Further reading
+
+- [Sequence Platform docs](${SEQUENCE_DOCS_URL})
+- [Create your first project](${SEQUENCE_DOCS_URL}projects/create-first-project)
+- [Artifact Studio](${SEQUENCE_DOCS_URL}artifact-studio/overview)
+- [Managed Functions](${SEQUENCE_DOCS_URL}managed-functions/overview)
+- [Managed Secrets](${SEQUENCE_DOCS_URL}managed-secrets/overview)
+- [Basketball player lookup](${SEQUENCE_DOCS_URL}examples/basketball-player-lookup)
+- [CLI command reference](${SEQUENCE_DOCS_URL}seq-studio/commands)
+- [Troubleshooting](${SEQUENCE_DOCS_URL}troubleshooting)
+`;
+}
+/** README for a brand-new git-service repo that does not yet have an app scaffold. */
+export function renderEmptyRepoReadme({ repoName, namespaceSlug, }) {
+    const title = titleizeSlug(repoName);
+    const qualified = namespaceSlug ? `${namespaceSlug}/${repoName}` : repoName;
+    return `${GIT_SERVICE_SEED_MARKER}\n${renderAppReadme({
+        appId: repoName,
+        title,
+        description: `Sequence Platform git-service repository \`${qualified}\`. Scaffold an app in this clone with \`seq-studio init\`, then validate and deploy with the same CLI.`,
+        primitives: ['orm', 'function', 'artifact'],
+        functionName: 'hello',
+    }).replace('## Implement this app', `## Scaffold the app
+
+This repository was created empty except for this README. From the clone root:
+
+\`\`\`bash
+# into this directory (keeps the git-service remote)
+seq-studio init . --with function,artifact --function-name hello --description "${title}"
+# or the intended three-primitive shape, once @sequenceholdings/orm v2 is available:
+# seq-studio init . --with orm,function,artifact --function-name hello
+\`\`\`
+
+\`init\` into a clone that only has this seed README (and \`.git\`) is allowed — it writes \`sequence.app.yml\` and the primitive folders, and replaces this file with an app-specific copy. \`init\` will not overwrite a README that does not contain the seed marker.
+
+## Implement this app`)}`;
+}
+function snake(appId) {
+    return appId.replace(/-/g, '_');
+}
+function renderAppTree({ appId, kinds, functionName, }) {
+    const lines = [
+        `${appId}/`,
+        '  README.md',
+        '  sequence.app.yml           primitives + deploy order',
+    ];
+    if (kinds.has('artifact')) {
+        lines.push('  artifact/                  Artifact Studio UI');
+    }
+    if (kinds.has('orm')) {
+        lines.push(`  orm/${snake(appId)}/             ORM namespace`);
+    }
+    if (kinds.has('function')) {
+        lines.push(`  functions/${functionName}/       Managed Function`);
+    }
+    return lines.join('\n');
+}
+function renderImplementSection({ kinds, functionName, appId, }) {
+    const steps = [];
+    if (kinds.has('function')) {
+        steps.push(`1. **Function** — implement \`functions/${functionName}/index.ts\`. Declare every outbound host under \`egress\` in \`managed-function.yml\` (the scaffold ships with none). Declare secret *names* in \`secrets:\` and keep values in an ignored \`functions/${functionName}/.env\`.
+
+   **Before \`pnpm install\`, delete \`functions/${functionName}/.npmrc\`** unless you have Sequence-internal Chainguard credentials. Without them that install 401s. Removing the file is the supported public path — the deploy worker re-resolves dependencies server-side.`);
+    }
+    if (kinds.has('orm')) {
+        steps.push(`2. **ORM** — author tables and named operations under \`orm/${snake(appId)}/\` (\`sequence.config.ts\`, \`schema/*.ts\`, \`graphql/**/*.ts\`). Then:
+
+   \`\`\`bash
+   seq-studio orm generate orm/${snake(appId)}
+   seq-studio orm plan orm/${snake(appId)} -e <environment-name>
+   seq-studio orm apply orm/${snake(appId)} -e <environment-name>
+   \`\`\`
+
+   Grant the artifact matching \`capabilities.data\` entries (\`<namespace>/<table>\` for reads, \`<namespace>/ops/<MutationName>\` for named writes) and the Data API paths you call.`);
+    }
+    if (kinds.has('artifact')) {
+        const n = steps.length + 1;
+        steps.push(`${n}. **UI** — \`artifact/src/App.tsx\` with \`@sequenceholdings/atlas-ui\`. Delete the scaffold's \`alert()\` Atlas ping; native \`alert\` / \`confirm\` / \`prompt\` are blocked in the sandbox.
+
+   If this app has a function, declare it and invoke it:
+
+   \`\`\`yaml
+   capabilities:
+     functions:
+       invoke:
+         - ${functionName}
+   \`\`\`
+
+   \`\`\`ts
+   import { seq } from './lib/api'
+   const result = await seq.functions.invoke('${functionName}', { /* input */ })
+   \`\`\`
+
+   \`pnpm dev\` in \`artifact/\` is standalone Vite. Platform calls only work inside Preview or an official Atlas deployment.`);
+    }
+    steps.push(`${steps.length + 1}. **Targets** — put your environment in \`artifact.bundle.yml\` \`targets\` (if this app has an artifact). Scaffolds create \`visibility: private\`. Set \`shared\` before first create if other people must open the app.
+
+${steps.length + 2}. **Validate, then deploy** from this directory:
+
+   \`\`\`bash
+   seq-studio deploy -e <environment-name> --dry-run
+   seq-studio deploy -e <environment-name> --yes
+   \`\`\`
+
+   \`--dry-run\` lists which primitives would run. Until \`git status\` is clean on \`main\`, use \`seq-studio artifact dev artifact -e <environment-name>\` for the UI.`);
+    return steps.join('\n\n');
+}

package/dist/app/scaffold.js

@@ -9,8 +9,48 @@ import { functionsInitCommand } from '../functions/commands.js';
 import { parseArgs } from '../process/commands.js';
 import { currentVersion } from '../update-check.js';
 import { defaultDeployOrder, extendDeployOrder, loadAppManifest, ormNamespaceFromAppId, titleizeSlug, writeAppManifest, } from './manifest.js';
+import { isGitServiceSeedReadme, renderAppReadme } from './readme.js';
 const LOG = '[seq-studio]';
 const APP_MANIFEST_LABEL = 'sequence.app.yml';
+/** Metadata a checkout may have without counting as a docs-only repository. */
+const INIT_METADATA_ONLY = new Set(['.git', '.gitattributes', '.DS_Store']);
+/**
+ * Extra names allowed beside a git-service seed README. Presence of any of
+ * these without that seed marker is treated as a non-empty user directory.
+ */
+const INIT_ALLOWED_EXISTING = new Set([
+    ...INIT_METADATA_ONLY,
+    '.gitignore',
+    'README.md',
+    'LICENSE',
+    'LICENSE.md',
+]);
+const DEFAULT_GITIGNORE_LINES = [
+    'node_modules/',
+    'dist/',
+    '.env',
+    '.env.*',
+    '!.env.example',
+    '.DS_Store',
+    '*.log',
+];
+/** Append missing Sequence ignores; keep existing lines and comments. */
+function mergeGitignore(existing) {
+    const defaults = DEFAULT_GITIGNORE_LINES;
+    if (existing === null) {
+        return `${defaults.join('\n')}\n`;
+    }
+    const present = new Set(existing
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('#')));
+    const missing = defaults.filter((line) => !present.has(line));
+    if (missing.length === 0) {
+        return existing.endsWith('\n') ? existing : `${existing}\n`;
+    }
+    const base = existing.endsWith('\n') ? existing : `${existing}\n`;
+    return `${base}${missing.join('\n')}\n`;
+}
 export function defaultScaffoldNames(_appId) {
     return { functionName: 'hello' };
 }
@@ -130,17 +170,36 @@ export async function initAppMonorepo({ rootDir, appId, kinds, names = defaultSc
     if (existsSync(join(appRoot, 'sequence.app.yml'))) {
         throw new Error(`${join(appRoot, 'sequence.app.yml')} already exists — refusing to re-init`);
     }
-    if (existsSync(appRoot)) {
-        const { readdir } = await import('node:fs/promises');
-        const entries = await readdir(appRoot).catch((error) => {
+    const { readdir } = await import('node:fs/promises');
+    const existed = existsSync(appRoot);
+    const entries = existed
+        ? await readdir(appRoot).catch((error) => {
             if (error.code === 'ENOENT')
                 return [];
             throw error;
-        });
-        if (entries.length > 0) {
-            throw new Error(`${appRoot} is not empty — init into a new directory, or remove existing files first`);
+        })
+        : [];
+    const unexpected = entries.filter((name) => !INIT_ALLOWED_EXISTING.has(name));
+    if (unexpected.length > 0) {
+        throw new Error(`${appRoot} is not empty — init into a new directory, a git-service clone whose README contains the seq-studio seed marker, or remove existing files first`);
+    }
+    const contentful = entries.filter((name) => !INIT_METADATA_ONLY.has(name));
+    if (contentful.length > 0) {
+        const readmePath = join(appRoot, 'README.md');
+        if (!existsSync(readmePath)) {
+            throw new Error(`${appRoot} is not empty — init into a git-service clone only when README.md contains the seq-studio git-service seed marker`);
+        }
+        const existingReadme = await readFile(readmePath, 'utf8');
+        if (!isGitServiceSeedReadme(existingReadme)) {
+            throw new Error(`${appRoot} already has a README.md that is not a git-service seed — refusing to overwrite it. Init into a new directory, or keep the platform-generated README from \`seq-studio repos create\`.`);
         }
     }
+    const previousReadme = existsSync(join(appRoot, 'README.md'))
+        ? await readFile(join(appRoot, 'README.md'), 'utf8')
+        : null;
+    const previousGitignore = existsSync(join(appRoot, '.gitignore'))
+        ? await readFile(join(appRoot, '.gitignore'), 'utf8')
+        : null;
     await mkdir(appRoot, { recursive: true });
     try {
         const version = currentVersion();
@@ -168,15 +227,59 @@ export async function initAppMonorepo({ rootDir, appId, kinds, names = defaultSc
             },
         };
         await writeAppManifest({ rootDir: appRoot, manifest });
-        await writeFile(join(appRoot, '.gitignore'), ['node_modules/', 'dist/', '.env', '.env.*', '!.env.example', '.DS_Store', '*.log'].join('\n') + '\n', 'utf8');
+        await writeFile(join(appRoot, '.gitignore'), mergeGitignore(previousGitignore), 'utf8');
+        await writeFile(join(appRoot, 'README.md'), renderAppReadme({
+            appId,
+            title: manifest.app.title,
+            description: manifest.app.description,
+            primitives: kinds,
+            functionName: names.functionName,
+        }), 'utf8');
         return manifest;
     }
     catch (error) {
-        // Directory was empty (or newly created) — remove partial scaffolds so a
-        // retry can `init` into the same path without a manual cleanup.
-        await rm(appRoot, { recursive: true, force: true }).catch(() => {
-            /* best-effort */
-        });
+        if (!existed) {
+            // Directory was newly created — remove the partial scaffold.
+            await rm(appRoot, { recursive: true, force: true }).catch(() => {
+                /* best-effort */
+            });
+        }
+        else {
+            // Reused a git-service clone — only remove what this invocation added.
+            await rm(join(appRoot, 'sequence.app.yml'), { force: true }).catch(() => {
+                /* best-effort */
+            });
+            for (const kind of kinds) {
+                const name = kind === 'function' ? names.functionName : appId;
+                const relPath = relativePathFor({ kind, appId, name }).replace(/\\/g, '/');
+                const top = relPath.split('/')[0];
+                if (top) {
+                    await rm(join(appRoot, top), { recursive: true, force: true }).catch(() => {
+                        /* best-effort */
+                    });
+                }
+            }
+            if (previousReadme !== null) {
+                await writeFile(join(appRoot, 'README.md'), previousReadme, 'utf8').catch(() => {
+                    /* best-effort */
+                });
+            }
+            else {
+                await rm(join(appRoot, 'README.md'), { force: true }).catch(() => {
+                    /* best-effort */
+                });
+            }
+            if (previousGitignore !== null) {
+                await writeFile(join(appRoot, '.gitignore'), previousGitignore, 'utf8').catch(() => {
+                    /* best-effort */
+                });
+            }
+            else {
+                await rm(join(appRoot, '.gitignore'), { force: true }).catch(() => {
+                    /* best-effort */
+                });
+            }
+        }
         throw error;
     }
 }
@@ -238,7 +341,7 @@ export function printInitNextSteps({ appRoot, manifest, }) {
     const rel = relative(process.cwd(), appRoot);
     const display = !rel || rel.startsWith('..') ? appRoot : rel;
     console.log(`${LOG} scaffolded app "${manifest.app.id}" in ${display}`);
-    console.log(`${LOG} wrote ${APP_MANIFEST_LABEL} with ${manifest.primitives.length} primitive(s):`);
+    console.log(`${LOG} wrote README.md (Sequence app docs) and ${APP_MANIFEST_LABEL} with ${manifest.primitives.length} primitive(s):`);
     for (const entry of manifest.primitives) {
         console.log(`${LOG}   - ${entry.kind.padEnd(9)} ${entry.id}  (${entry.path})`);
     }

package/dist/auth.d.ts

@@ -53,14 +53,17 @@ export interface SeqapiTokens {
     access_token?: string;
     expires_at?: number;
 }
+interface RealmResolutionOptions {
+    fetchImpl?: typeof fetch;
+    targetUrl?: string;
+}
 /**
  * Resolve the auth realm for an environment name. Undefined, built-ins, and
- * per-PR preview targets map to the shared Sequence realm. Preview URLs are
- * constrained to Sequence's preview domain by the environment resolver. Every
- * other explicit name must have a valid seqapi registry entry; otherwise fail
- * closed so a shared Sequence bearer token can never be sent to a tenant URL.
+ * per-PR preview targets map to the shared Sequence realm, except loopback
+ * targets can advertise the isolated Sequence-staging realm used by contractor
+ * local dev. Every other explicit name must have a valid seqapi registry entry.
  */
-export declare function realmForEnv(envName?: string): Promise<AuthRealm>;
+export declare function realmForEnv(envName?: string, options?: RealmResolutionOptions): Promise<AuthRealm>;
 /** Env var(s) carrying a realm's M2M client secret — the Sequence realm keeps
  * the legacy bare name; OpCo realms use a suffixed name so one shell can hold
  * several credentials unambiguously. Mirrors seqapi's `_m2m_secret_env_names`. */
@@ -153,3 +156,4 @@ export declare function currentIdentitySubject(options?: {
 export declare function loadCachedUserTokens(realmName?: string): Promise<SeqapiTokens | null>;
 export declare function saveTokens(tokens: SeqapiTokens, realmName?: string): Promise<void>;
 export declare function deleteRealmTokens(realmName: string): Promise<void>;
+export {};