@layers/amba 1.1.0 → 4.0.2

package/dist/sandbox.d.ts

@@ -47,7 +47,7 @@ export interface SandboxSignupRequest {
 /**
  * Shape returned by `POST /v1/auth/developer/signup`. Only the fields the
  * sandbox flow actually consumes are typed — the response body has more
- * (developer row, token expiry, etc.) but we don't need them here.
+ * (refresh token, expiry, etc.) but we don't need them here.
  */
 export interface SandboxSignupResponse {
     pat: string;
@@ -61,6 +61,15 @@ export interface SandboxSignupResponse {
     verify_url?: string;
     /** The actual email we used (may be the auto-generated one). */
     email: string;
+    /**
+     * Developer row returned in `data.developer`. Required for callers
+     * (e.g. `ensureDeveloperIdentity`) to populate the developer_id on
+     * the freshly-minted local credentials without a second round trip
+     * to `/developer/me`.
+     */
+    developer_id: string;
+    /** Developer name, if set on the row. */
+    developer_name?: string;
 }
 export interface McpClientConfigTarget {
     /** Display name for logging. */
@@ -96,6 +105,18 @@ export interface SandboxResult {
      * (e.g. `--no-skills`).
      */
     skillPath: string | null;
+    /**
+     * Per-agent setup-guide fan-out result. One entry per writer that
+     * succeeded. Empty array when `--no-skills` was passed (the same flag
+     * gates both the build-task skill and the cross-agent fan-out — they
+     * write into the same project surfaces and there's no use-case for
+     * skipping one but not the other).
+     */
+    setupTargets: Array<{
+        target: string;
+        path: string;
+        mode: 'created' | 'refreshed';
+    }>;
 }
 /**
  * Generate a deterministic-looking but globally-unique sandbox email.
@@ -142,48 +163,21 @@ export declare function performSandboxSignup(req: SandboxSignupRequest, options?
     apiUrl?: string;
     fetchImpl?: typeof fetch;
 }): Promise<SandboxSignupResponse>;
-/**
- * Result of writing sandbox credentials. The optional `backedUpTo` lets
- * the CLI surface a "we moved your existing creds aside" notice so a
- * developer who accidentally ran `--sandbox` on top of a real OAuth
- * session can recover.
- */
-export interface WriteCredentialsResult {
-    path: string;
-    /** Absolute path of the backup file, or null if no backup was made. */
-    backedUpTo: string | null;
-}
-/**
- * Write the PAT to `~/.amba/credentials.json` (chmod 0600) in a shape
- * the existing `loadCredentials` reader recognises.
- *
- * `auth.ts` was built around browser-OAuth tokens (`access_token` +
- * `refresh_token` + `expires_at`). PATs are long-lived and don't refresh
- * — but the stored-creds reader only inspects `access_token`, so we
- * write the PAT there and leave `refresh_token` empty + a far-future
- * `expires_at` so the expiry guard never fires.
- *
- * Real-credential safety: if the file already exists AND its `source`
- * is NOT `'sandbox-init'` AND `access_token` is non-empty, we treat it
- * as a real OAuth/PAT session and back it up to
- * `credentials.json.bak-<unix-ms>` before overwriting. The next
- * `--sandbox` run reuses our own previous sandbox creds without
- * back-up. This keeps the agentic flow idempotent while preventing a
- * silent clobber of a developer's real account.
- */
-export declare function writeSandboxCredentials(pat: string, options?: {
-    homeDir?: string;
-}): Promise<WriteCredentialsResult>;
 /**
  * Write or update `<cwd>/.env.local` with the sandbox project's keys.
  *
  * Mirrors the `init` interactive flow exactly so the existing env-read
  * conventions in the SDKs and CLI commands keep working. The merge
  * logic: if the file already exists and contains an `AMBA_PROJECT_ID`
- * line we replace the three Amba lines in place; otherwise we append a
+ * line we replace the Amba lines in place; otherwise we append a
  * fresh stanza.
+ *
+ * `serverKey` is optional — pass it on the new two-scope credential
+ * model where init mints both client+server. Pre-existing AMBA_SERVER_KEY
+ * lines are refreshed when a new value is provided and removed when
+ * serverKey is null AND no prior line existed (no-op on second case).
  */
-export declare function writeSandboxEnvLocal(cwd: string, projectId: string, clientKey: string, apiUrl: string): Promise<string>;
+export declare function writeSandboxEnvLocal(cwd: string, projectId: string, clientKey: string, apiUrl: string, serverKey?: string | null): Promise<string>;
 /**
  * Write the AMBA.md sandbox-tier guide to `<cwd>/AMBA.md`.
  *
@@ -212,8 +206,12 @@ export declare function writeSandboxAmbaMd(cwd: string, ctx: {
 export declare function buildAmbaMcpEntry(pat: string): Record<string, unknown>;
 /**
  * Identifier for the MCP client family a config file belongs to.
- * Used by the CLI's done-message to print per-client restart bullets
- * — and only for clients whose config we actually wrote to.
+ * Kept around so callers can reason about which agent runtime a given
+ * config path targets — the CLI no longer prints per-client restart
+ * bullets (the new flow frames MCP wiring as "active next agent
+ * launch" rather than asking the developer to restart), but the
+ * classifier is still useful for callers that want to render per-
+ * client labels in their own UI.
  */
 export type McpClientKind = 'claude-code' | 'cursor' | 'windsurf';
 /**

package/dist/skill-installer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Amba skill bundle installer.
+ *
+ * The bundled `skill-bundle/` directory contains `SKILL.md` plus a
+ * `references/` folder with one file per Amba surface area. The skill
+ * teaches the agent the classify → confirm → wire-up playbook for
+ * adding Amba primitives to a developer's codebase. See
+ * `packages/cli/skill-bundle/SKILL.md` for the source.
+ *
+ * Why ship a bundled skill (instead of `npx skills add layers/amba`):
+ * the CLI run is the same install step. Bundling avoids a second
+ * fetch, keeps the skill version locked to the CLI version, and means
+ * `amba init` produces a fully-wired agent on offline networks too.
+ *
+ * Cross-agent install — we drop the same body into every detected
+ * coding agent's skill directory. Agents read their own location:
+ *
+ *   - Claude Code:  `.claude/skills/amba/`
+ *   - Cursor:       `.cursor/skills/amba/`
+ *   - Codex CLI:    `.codex/skills/amba/`
+ *   - Windsurf:     `.windsurf/skills/amba/`
+ *
+ * We also write a project-root copy at `.agents/skills/amba/` which
+ * the `npx skills add ...` distribution tool reads from (and which any
+ * agent that pre-registers an `.agents/skills/` lookup picks up). Five
+ * locations, one body — same fan-out pattern `writeAllSetupTargets`
+ * already uses for the legacy setup guide.
+ *
+ * Idempotency: re-running `amba init` overwrites the bundled
+ * `SKILL.md` and `references/*.md` so every developer ends up on the
+ * latest playbook. We back up a pre-existing `SKILL.md` to a sibling
+ * `.bak-<unix-ms>` ONLY when its first frontmatter key (`name:`) is
+ * not `amba` — that's the signal it was hand-authored / unrelated and
+ * shouldn't be silently clobbered. Bundled Amba files are refreshed
+ * without backup.
+ */
+export type SkillInstallTargetKind = 'claude-code' | 'cursor' | 'codex' | 'windsurf' | 'generic-agents';
+export interface SkillInstallTarget {
+    kind: SkillInstallTargetKind;
+    /** Absolute path to the `amba/` directory inside the agent's skill root. */
+    path: string;
+}
+export interface SkillFileWritten {
+    /** Absolute path of the file written. */
+    path: string;
+    /** Backup path when an existing non-Amba SKILL.md was preserved; otherwise null. */
+    backedUpTo: string | null;
+}
+export interface SkillInstallResult {
+    /** Target directory the skill was installed under. */
+    target: SkillInstallTarget;
+    /** Files written this run. */
+    files: SkillFileWritten[];
+}
+/**
+ * Resolve the bundled skill source directory.
+ *
+ * The bundle lives at `<package-root>/skill-bundle/` in both the
+ * source tree and the published tarball (via `files[]` in
+ * `package.json`). From a built `dist/commands/init.js` the path is
+ * `../../skill-bundle/`. From the source tree
+ * (`src/skill-installer.ts`) the path is `../skill-bundle/`. We try
+ * both relative to `import.meta.url` and pick the one that exists.
+ */
+export declare function resolveBundleDir(): Promise<string>;
+/**
+ * List the five install targets the CLI fans out to. Project-local
+ * directories (`<cwd>/.claude/skills/amba/`, etc.) — the agent reads
+ * project-local skills with priority over global ones, so this is the
+ * canonical install location for a tool meant to wire up THIS project.
+ */
+export declare function skillInstallTargets(cwd: string): SkillInstallTarget[];
+/**
+ * Copy SKILL.md + every file under references/ into the target
+ * directory. Creates the directory tree if missing. Returns the list
+ * of files touched and any backup paths.
+ *
+ * Backup rule: a pre-existing `SKILL.md` is backed up to
+ * `SKILL.md.bak-<unix-ms>` ONLY when its first `name:` frontmatter
+ * line is NOT `name: amba`. That's the signal it was authored by the
+ * user for an unrelated purpose and shouldn't be silently overwritten.
+ * Amba-owned files get refreshed without backup so developers
+ * tracking the latest playbook don't accumulate junk.
+ */
+export declare function installSkillBundle(cwd: string, options?: {
+    bundleDir?: string;
+}): Promise<SkillInstallResult[]>;
+/**
+ * Convenience: returns the count of skill files written and the list
+ * of target kinds, for the CLI's done-message summary.
+ */
+export declare function summarizeSkillInstall(results: SkillInstallResult[]): {
+    totalFiles: number;
+    targetKinds: SkillInstallTargetKind[];
+};

package/dist/skills/presets.d.ts

@@ -0,0 +1,146 @@
+/**
+ * App-kind presets for the "Hey Claude, get amba.dev in my app" onboarding.
+ *
+ * The classifier picks one of 10 kinds (9 opinionated + `custom`); the
+ * wire-up engine reads the matching preset to know:
+ *
+ *   - which Amba surface areas to enable (used to scope the docs the
+ *     coding agent pulls into context),
+ *   - which follow-up questions to ask the developer when the preset has
+ *     genuine ambiguity (e.g. friends-vs-global leaderboard scope),
+ *   - the exact MCP tool calls to issue against `mcp.amba.dev` to create
+ *     the starter resources (currencies, achievements, streaks, …),
+ *   - the literal SDK init snippet to paste into the developer's project
+ *     for whichever of the six supported stacks they're on.
+ *
+ * The MCP tool names and argument shapes here MUST match the registered
+ * tools in `packages/mcp/src/tools/*`. The validation surface for that
+ * is the per-tool zod schema; this file is the single source of truth
+ * for "what does Amba install for a fitness app" and lives in the CLI
+ * because the CLI's classifier (Task #3) reads it directly. The MCP
+ * server doesn't import this — its job is to expose the underlying
+ * tools, not to know about preset choices.
+ *
+ * Naming discipline (see CLAUDE.md): no `cf_*` / `neon_*` / `temporal_*`
+ * field names; achievement icons reference customer-replaceable URLs on
+ * the Amba CDN; SDK snippets never name an underlying vendor.
+ */
+/**
+ * The closed set of app kinds the classifier returns. `custom` is the
+ * escape hatch — when the classifier can't confidently pick, the CLI
+ * presents the full surface-area picker instead of applying a preset.
+ */
+export type AppKind = 'fitness' | 'social' | 'marketplace' | 'productivity' | 'education' | 'game' | 'dating' | 'content_creator' | 'ai_chatbot' | 'custom';
+/**
+ * The surface areas (Amba primitives) a preset can opt into.
+ *
+ * `identity` is implicit in every preset — anonymous user provisioning is
+ * a precondition of every other surface — but listing it explicitly in
+ * `surfaces` makes the wire-up output self-describing.
+ */
+export type AmbaSurface = 'identity' | 'xp' | 'streaks' | 'achievements' | 'leaderboards' | 'currencies' | 'catalog' | 'stores' | 'inventory' | 'friendships' | 'groups' | 'feeds' | 'messaging' | 'moderation' | 'reviews' | 'push' | 'content' | 'referrals' | 'deeplinks' | 'segments' | 'onboarding' | 'ai_prompts';
+/** The 6 SDK stacks for which we emit a copy-pasteable init snippet. */
+export type SdkStack = 'expo' | 'reactNative' | 'web' | 'swift' | 'kotlin' | 'flutter';
+export interface FollowUpOption {
+    value: string;
+    label: string;
+    /**
+     * Marks the option the CLI selects by default if the developer accepts
+     * the recommended answer without interaction. Exactly zero or one
+     * option per question carries this flag.
+     */
+    recommended?: boolean;
+}
+export interface FollowUpQuestion {
+    /** The surface the answer mutates. Used by the wire-up engine to route. */
+    surface: AmbaSurface;
+    /**
+     * Stable identifier used to look up the answer in the wire-up engine.
+     * Tied to `WireUpAction.dependsOn` references.
+     */
+    id: string;
+    question: string;
+    options: FollowUpOption[];
+}
+/**
+ * A single MCP tool call the wire-up engine should issue.
+ *
+ * `args` mirrors the tool's zod input schema MINUS `project_id`, which
+ * the engine injects from the active project context — the developer
+ * never passes a project id at this layer.
+ *
+ * `dependsOn` is the id of a follow-up question whose answer mutates
+ * the action (e.g. leaderboard scope drives `metric` / `name`). The
+ * engine reads the answer, applies `whenAnswer` to transform `args`,
+ * and skips the action entirely if `whenAnswer` returns `null`.
+ */
+export interface WireUpAction {
+    tool: string;
+    args: Record<string, unknown>;
+    /**
+     * Optional follow-up dependency. The engine resolves the developer's
+     * answer to `dependsOn.id`, then calls `dependsOn.whenAnswer(value)`
+     * to produce the final args. Returning `null` means "skip this
+     * action for that answer."
+     */
+    dependsOn?: {
+        id: string;
+        whenAnswer: (answer: string) => Record<string, unknown> | null;
+    };
+}
+export interface SdkInitSnippets {
+    /** Expo (managed) — uses `@layers/amba-expo`. */
+    expo: string;
+    /** Bare React Native — uses `@layers/amba-react-native`. */
+    reactNative: string;
+    /** Browser / SSR — uses `@layers/amba-web`. */
+    web: string;
+    /** iOS / macOS / tvOS / watchOS — Swift Package Manager. */
+    swift: string;
+    /** Android — Maven Central artifact `com.layers.amba:amba-sdk-android`. */
+    kotlin: string;
+    /** Flutter / Dart — `amba` on pub.dev. */
+    flutter: string;
+}
+export interface AppKindPreset {
+    kind: AppKind;
+    label: string;
+    description: string;
+    /**
+     * Surfaces to enable. `identity` always appears first — every preset
+     * requires user identity. The order in the array is the order the
+     * wire-up engine renders to the developer (logical, not arbitrary).
+     */
+    surfaces: AmbaSurface[];
+    /**
+     * Genuinely ambiguous choices the developer needs to make. Decisions
+     * with a clear default (e.g. "should we install identity?" — yes,
+     * always) are NOT follow-ups; they're baked into `wireUp.actions`.
+     */
+    followUpQuestions: FollowUpQuestion[];
+    wireUp: {
+        actions: WireUpAction[];
+        sdkInit: SdkInitSnippets;
+    };
+}
+/**
+ * Canonical preset registry. Lookup is by `AppKind`; iteration order is
+ * the order the CLI presents to the developer when classification is
+ * ambiguous and we fall back to a manual menu (alphabetical-ish by
+ * common usage, with `custom` last).
+ */
+export declare const PRESETS: Record<AppKind, AppKindPreset>;
+/**
+ * Ordered list of the 9 non-custom presets. Useful when the CLI
+ * renders the "pick an app type" menu — `custom` is appended by the
+ * caller as the final escape-hatch option.
+ */
+export declare const PRESET_ORDER: readonly AppKind[];
+/**
+ * Type-narrowing helper for the classifier output. Returns the preset
+ * verbatim when the kind is known; the caller is expected to surface a
+ * helpful error if classification produced a value outside the closed
+ * set (the type system blocks that in TypeScript, but the boundary
+ * between classifier-JSON and this module is a runtime trust check).
+ */
+export declare function getPreset(kind: AppKind): AppKindPreset;

package/dist/skills.d.ts

@@ -1,31 +1,45 @@
 /**
- * Claude Code skill installer for `amba init --sandbox`.
- *
- * Writes a project-local `.claude/skills/amba-build/SKILL.md` file
- * containing the canonical "/goal" prompt for building a full Expo
- * app with Amba as the only backend. Two behaviors:
- *
- *   1. **Live fetch first.** The skill's runtime instructions tell
- *      Claude Code to `curl` the live MDX from
- *      `https://docs.amba.dev/docs/prompts/expo-build.md`. So as long
- *      as docs is reachable, the agent always uses the latest version.
- *
- *   2. **Inlined snapshot fallback.** The same SKILL.md file embeds a
- *      verbatim copy of the prompt body — captured at CLI install
- *      time from `@layers/amba-mcp/prompts`. Offline agents (or ones
- *      whose curl 404s during the docs deploy gap) still get a
- *      usable prompt.
- *
- * Out of scope (per DX-16): Cursor / Windsurf shortcut files. Those
- * editors don't ingest Claude Code skills; their users paste the
- * URL directly. The CLI's success line still surfaces the
- * `/amba-build` command + the docs URL so both audiences are served.
- *
- * Project-local install is the default because skills written into
- * `~/.claude/skills/` are user-global and would persist across
- * unrelated projects (and accumulate stale copies of the inlined
- * snapshot from old `amba init` runs). A project-scoped install
- * disappears when the user `rm -rf`s the project.
+ * Per-agent skill / rule file installer for `amba init`.
+ *
+ * Two distinct surfaces, both project-local:
+ *
+ *   1. **Build task skill** — `.claude/skills/amba-build/SKILL.md`.
+ *      Scaffolds a full Expo app via the canonical "/goal" prompt.
+ *      Task-shaped: the user invokes it explicitly. Lives behind
+ *      `writeAmbaBuildSkill` (legacy export, unchanged).
+ *
+ *   2. **Reference / setup skill** — fanned out into five locations,
+ *      one per agent family, so the same Amba setup guide reaches
+ *      whatever coding agent the user has installed:
+ *
+ *      | Surface                                  | Path                          | Wrapper                  |
+ *      |------------------------------------------|-------------------------------|--------------------------|
+ *      | Claude Code (proactive, auto-injected)   | \`CLAUDE.md\` (append)          | plain markdown           |
+ *      | Claude Code (invokable skill)            | \`.claude/skills/amba/SKILL.md\` | \`description:\` frontmatter |
+ *      | Cursor                                   | \`.cursor/rules/amba.mdc\`      | \`alwaysApply\`/\`description\`/\`globs\` |
+ *      | Codex / Aider / Zed / Copilot / Gemini   | \`AGENTS.md\` (append)          | plain markdown           |
+ *      | Windsurf                                 | \`.windsurf/rules/amba.md\`     | \`trigger: always_on\`     |
+ *
+ * The two append targets (\`CLAUDE.md\`, \`AGENTS.md\`) use marker
+ * fencing — \`<!-- AMBA-SETUP-START -->\` / \`<!-- AMBA-SETUP-END -->\` —
+ * so a re-init refreshes only Amba's section without clobbering user
+ * edits to the surrounding file. The standalone targets (\`.cursor\`,
+ * \`.windsurf\`, \`.claude/skills/amba\`) live in their own files and
+ * are overwritten wholesale per re-init.
+ *
+ * The shared body comes from \`@layers/amba-mcp/prompts\`
+ * (\`AMBA_SETUP_GUIDE_MD\`) — one canonical source, five wrappers. The
+ * CLI bundles that constant at publish time via tsdown's
+ * \`noExternal: [/^@layers\\/amba-/]\` rule (same path \`EXPO_BUILD_PROMPT_MD\`
+ * already uses).
+ *
+ * Vendor-name discipline
+ * ----------------------
+ * Everything written by this module is customer-facing. The body
+ * (sourced from the MCP package) is vetted there; the wrappers below
+ * intentionally avoid naming Cloudflare / GCP / Neon / Temporal /
+ * Rust / WASM / UniFFI / Resend / Doppler. See \`skills.test.ts\` for
+ * the per-writer drift gate.
  */
 export interface WriteAmbaBuildSkillOptions {
     /**
@@ -45,31 +59,208 @@ export interface WriteAmbaBuildSkillResult {
  * Exported as a pure function so the unit tests can assert structural
  * properties (frontmatter, fetcher block, inlined snapshot fence)
  * without round-tripping through the filesystem.
- *
- * Structure:
- *   1. YAML frontmatter — `description` so Claude Code's skill
- *      indexer picks it up.
- *   2. Skill body — invocation instructions, fetcher one-liner,
- *      fallback rule.
- *   3. Inlined snapshot — fenced code block containing the
- *      EXPO_BUILD_PROMPT_MD body verbatim. The snapshot is bounded
- *      by a marker comment so a future `amba update-skills` command
- *      can find and refresh just the inlined region without
- *      clobbering user customizations above it.
  */
 export declare function buildAmbaBuildSkillContent(): string;
 /**
  * Write `.claude/skills/amba-build/SKILL.md` into the target project.
+ * Always overwrites — the inlined snapshot is meant to be regenerated
+ * on each `amba init --sandbox` run.
+ */
+export declare function writeAmbaBuildSkill(options?: WriteAmbaBuildSkillOptions): Promise<WriteAmbaBuildSkillResult>;
+/**
+ * Common write-option shape for every per-agent writer. The only knob
+ * is `baseDir` — the project root we anchor relative paths against.
+ * Production callers pass `cwd`; tests pass a tmp dir.
+ */
+export interface WriteSetupTargetOptions {
+    baseDir?: string;
+}
+/** Result returned by every per-agent writer. */
+export interface WriteSetupTargetResult {
+    /** Absolute path of the file we wrote (or refreshed). */
+    path: string;
+    /**
+     * `'created'` when the file did not exist before this call,
+     * `'refreshed'` when we updated an existing file (overwrote a
+     * standalone file or refreshed a marker-fenced region in an
+     * append-target).
+     */
+    mode: 'created' | 'refreshed';
+}
+/** Identifier for each fan-out target. */
+export type SetupTarget = 'claude-md' | 'claude-skill' | 'cursor-rule' | 'agents-md' | 'windsurf-rule';
+/**
+ * Marker fence sentinels for the two append-targets (`CLAUDE.md`,
+ * `AGENTS.md`). Used by `markerFencedAppend` to find + refresh the
+ * Amba section without clobbering surrounding user content.
+ */
+export declare const AMBA_SETUP_START_MARKER = "<!-- AMBA-SETUP-START -->";
+export declare const AMBA_SETUP_END_MARKER = "<!-- AMBA-SETUP-END -->";
+/**
+ * Thrown by `markerFencedAppend` when the target file does not
+ * contain exactly one `<start>` and one `<end>` marker in canonical
+ * order (end after start). Any deviation — orphan single marker,
+ * duplicate paired blocks, end-before-start, mixed counts — is
+ * treated as corruption and surfaced to the caller.
  *
- * Always overwrites — the skill file is meant to be regenerated each
- * time `amba init --sandbox` runs (so the inlined snapshot stays
- * fresh). Anything the user customized above the snapshot markers
- * would be lost on a re-init; that's an accepted trade-off for the
- * agentic single-command flow.
+ * The helper refuses to auto-recover because every other shape risks
+ * deleting user content outside the Amba block (e.g. a stray end
+ * marker in user-authored text would cause a strip pass to remove
+ * everything above it). The caller's `warn` sink shows the developer
+ * the path + marker counts so they can resolve manually and re-run
+ * `amba init`.
  *
- * If a future need for "preserve user edits across re-init" surfaces,
- * the right shape is a separate `amba update-skills` command that
- * surgically rewrites the inlined-snapshot region only — leaving the
- * surrounding text untouched. Out of scope for DX-16.
+ * The counts + indices the helper observed at the moment of failure
+ * are exposed on the error so tests + tooling can introspect without
+ * regex-scraping the message.
  */
-export declare function writeAmbaBuildSkill(options?: WriteAmbaBuildSkillOptions): Promise<WriteAmbaBuildSkillResult>;
+export interface AmbaSkillFileMarkerShape {
+    startCount: number;
+    endCount: number;
+    /** Index of the first start marker, or -1 if absent. */
+    startIdx: number;
+    /** Index of the first end marker, or -1 if absent. */
+    endIdx: number;
+}
+export declare class AmbaSkillFileCorrupted extends Error {
+    readonly path: string;
+    readonly shape: AmbaSkillFileMarkerShape;
+    constructor(filePath: string, shape: AmbaSkillFileMarkerShape);
+}
+/**
+ * Insert or refresh a marker-fenced block in a file.
+ *
+ * Marker-shape invariant: the target file must have either
+ *   (a) zero start/end markers (clean append), or
+ *   (b) exactly one start marker and one end marker, with the end
+ *       marker after the start (clean in-place refresh).
+ *
+ * Any other shape — orphan single marker, duplicate paired blocks,
+ * end-before-start, mixed counts (e.g. 1 start + 2 ends) — is
+ * treated as corruption and throws `AmbaSkillFileCorrupted`. The
+ * caller's `warn` sink surfaces the error to the developer; the
+ * file is left untouched. Earlier revisions tried to auto-recover
+ * malformed states via strip-and-replace, but every recovery
+ * heuristic risked deleting user content outside the Amba block
+ * (BugBot cycle-5..7 all flagged adjacent failure modes — the
+ * strict invariant kills the whole class).
+ *
+ * Behavior:
+ *
+ *   - File does not exist (`ENOENT`) → create with just the block.
+ *     **Any other read error (EACCES, EISDIR, transient I/O) is
+ *     re-thrown** — we never silently overwrite a file we couldn't
+ *     read.
+ *   - File exists, zero markers → append the block (with a blank-
+ *     line separator so it doesn't fuse onto the last paragraph).
+ *   - File exists, well-formed 1+1 pair (end after start) → replace
+ *     the content between markers, preserving surrounding text.
+ *   - Any other marker shape → throw `AmbaSkillFileCorrupted` with
+ *     the observed (startCount, endCount, startIdx, endIdx).
+ *
+ * Returns the absolute path + whether this was a fresh create or a
+ * refresh.
+ *
+ * The `body` argument is the text we want **inside** the markers —
+ * the markers themselves are added by this helper. Callers must NOT
+ * include the start/end marker lines in `body`.
+ */
+export declare function markerFencedAppend(filePath: string, body: string, startMarker: string, endMarker: string): Promise<WriteSetupTargetResult>;
+/**
+ * Build the canonical setup body. Sourced from the MCP package so
+ * docs + MCP + every coding-agent surface stay in sync.
+ *
+ * Exposed as a function (not a const) so future versions can swap in
+ * a build-time generator without breaking import sites.
+ */
+export declare function buildAmbaSetupBody(): string;
+/**
+ * Build the Claude-Code-skill flavor of the setup guide
+ * (`.claude/skills/amba/SKILL.md`).
+ *
+ * The `description:` frontmatter is what Claude Code's skill indexer
+ * reads to decide whether to invoke the skill. Spell out every Amba
+ * primitive family so a model reasoning over "this app needs push
+ * notifications" or "we want gamification" maps the request onto
+ * Amba primitives rather than re-rolling a backend.
+ */
+export declare function buildClaudeSkillContent(): string;
+/**
+ * Build the Cursor `.cursor/rules/amba.mdc` flavor.
+ *
+ * `alwaysApply: true` makes Cursor inject the rule at the start of
+ * every turn (Cursor's most-proactive mode). `globs: ""` keeps the
+ * rule globally-scoped instead of file-pattern-attached.
+ */
+export declare function buildCursorRuleContent(): string;
+/**
+ * Build the Windsurf `.windsurf/rules/amba.md` flavor.
+ *
+ * `trigger: always_on` is Windsurf's equivalent of Cursor's
+ * `alwaysApply: true`. Workspace rules **cap at 12k chars** — a hard
+ * Windsurf limit, not negotiable. The canonical
+ * `AMBA_SETUP_GUIDE_MD` body is the full classify → confirm →
+ * wire-up playbook (~17k) and won't fit, so Windsurf gets a
+ * trimmed-down summary that points at the long-form resource
+ * (`amba://setup`) for full detail. Same posture as
+ * `AMBA_INIT_INSTRUCTIONS` in the hosted MCP server.
+ */
+export declare function buildWindsurfRuleContent(): string;
+/**
+ * Body for the marker-fenced append into `CLAUDE.md` or `AGENTS.md`.
+ *
+ * Plain markdown, no frontmatter — both conventions are
+ * frontmatter-free. Returns the inner body only; the marker fence is
+ * added by `markerFencedAppend`.
+ */
+export declare function buildAppendableSetupBody(): string;
+/**
+ * Write `.claude/skills/amba/SKILL.md` — the **reference** Claude Code
+ * skill. (The build-task skill `.claude/skills/amba-build/SKILL.md`
+ * is separate; see `writeAmbaBuildSkill`.)
+ */
+export declare function writeAmbaSkill(options?: WriteSetupTargetOptions): Promise<WriteSetupTargetResult>;
+/** Write `.cursor/rules/amba.mdc`. */
+export declare function writeCursorRule(options?: WriteSetupTargetOptions): Promise<WriteSetupTargetResult>;
+/** Write `.windsurf/rules/amba.md`. */
+export declare function writeWindsurfRule(options?: WriteSetupTargetOptions): Promise<WriteSetupTargetResult>;
+/**
+ * Append (or refresh) the Amba setup section in `CLAUDE.md` at the
+ * project root. Marker-fenced so it can be safely refreshed by
+ * subsequent re-inits.
+ */
+export declare function writeClaudeMd(options?: WriteSetupTargetOptions): Promise<WriteSetupTargetResult>;
+/**
+ * Append (or refresh) the Amba setup section in `AGENTS.md` at the
+ * project root. The `AGENTS.md` convention is read by 20+ agentic
+ * tools (Codex, Aider, Zed, Copilot, Gemini CLI, Warp, etc.) so this
+ * single file covers most of the long tail.
+ */
+export declare function writeAgentsMd(options?: WriteSetupTargetOptions): Promise<WriteSetupTargetResult>;
+/**
+ * Convenience: emit ALL five setup-guide targets in one call. Used by
+ * `amba init` so a single sandbox provision drops Amba context into
+ * whatever agent the developer happens to have configured.
+ *
+ * Each writer is best-effort independent — a failure in one (e.g. the
+ * filesystem rejects a write under one of the dot-prefixed dirs)
+ * doesn't prevent the others from succeeding. Errors are captured
+ * per-target and surfaced via the optional `warn` callback so the
+ * caller can decide whether to fail the parent flow.
+ */
+export interface WriteAllSetupTargetsOptions {
+    baseDir?: string;
+    /** Per-target failure sink. Defaults to a no-op. */
+    warn?: (message: string) => void;
+}
+export interface WriteAllSetupTargetsResult {
+    /** Per-target outcome, indexed by `SetupTarget`. */
+    written: Array<{
+        target: SetupTarget;
+        path: string;
+        mode: 'created' | 'refreshed';
+    }>;
+    /** Body version stamped into each file (echoed via the marker). */
+    bodyVersion: string;
+}
+export declare function writeAllSetupTargets(options?: WriteAllSetupTargetsOptions): Promise<WriteAllSetupTargetsResult>;