> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edgespark.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# EdgeSpark documentation

## Product context

EdgeSpark is an **agent-native harness platform** — not a framework. It deploys full-stack web apps to Cloudflare's edge and guides AI coding agents to write safer code via path-based auth, SQL validation, and storage isolation. Two primary users: human developers (owners) and AI coding agents (builders).

## Maintaining this file

Update CLAUDE.md whenever you discover a mistake, fix a recurring bug, or learn something that would prevent future errors. This file is the main way knowledge persists across sessions.

## Syncing docs with edge-spark codebase

`edge-spark/` is a git submodule of the platform codebase. `.edge-spark-synced` stores the last edge-spark commit SHA that docs were verified against — the script reads it as the baseline for computing diffs.

Do NOT run this automatically. Only when the user explicitly asks to sync or check edge-spark changes:

1. Run `bash scripts/diff-codebase.sh` — pulls latest edge-spark, diffs from `.edge-spark-synced` SHA to HEAD, writes log to `.diff-logs/`
2. Read the log, explore `edge-spark/` to understand the changes
3. Update the affected doc pages — work through every changed file in the log; commit incrementally as each page is done. Only move to step 4 when every item in the diff log has been addressed (updated or confirmed unaffected).
4. Write the new SHA to `.edge-spark-synced`: `git -C edge-spark rev-parse HEAD > .edge-spark-synced`
5. Commit `.edge-spark-synced`, `edge-spark`, and the updated docs together

For regular docs work (typos, rewrites, new pages) — just edit and commit. No sync needed.

## Documentation architecture

Three tabs — maintain this structure, extend within it:

1. **Documentation** — for human developers: Getting started → Concepts → Build → Deploy
2. **For AI Agents** — agent operating manual: Overview → Working with EdgeSpark → Agent setup
3. **Reference** — lookup content: CLI → SDK → Platform limits

Always add new pages to the correct group in `docs.json` or they won't appear in navigation. Placeholder pages are acceptable and preferred over missing sections.

## Content rules

* External docs only — no internal service names, infrastructure internals, or RPC details
* Self-contained pages — define EdgeSpark-specific terms on first use
* Task-oriented guide titles — "Use the database" not "Database"
* Complete code examples — always include imports, file labels (`src/index.ts`), and all referenced functions. Never reference undefined helpers.
* Separate and label server-side vs client-side code blocks
* Secrets docs must explicitly say secret values never pass through terminal output, agent context, or third-party LLM APIs such as Anthropic, Google, or OpenAI; they are entered through a secure EdgeSpark browser URL
* Search for existing content before adding. Avoid duplication.

## Frontmatter (required on every MDX file)

* `title`: specific and searchable (e.g. `"client.db — Database"` not `"Database"`)
* `description`: 120–155 characters, action + technology + benefit
* `keywords`: array of longtail search terms (used by Mintlify internal search and `llms.txt`, not Google)

## Writing standards

* Second-person voice ("you"), sentence case for headings
* Language tags on all code blocks; file path labels (`src/index.ts`, `client.ts`)
* Relative root paths for internal links (`/guides/database` not `../database`)
* No emoji unless explicitly requested
* Link to `/reference/limits` whenever mentioning a constraint or limit

## "See also" pattern

End every guide and SDK reference page with:

```mdx theme={null}
<Columns cols={2}>
  <Card title="..." icon="..." href="/...">...</Card>
  <Card title="..." icon="..." href="/...">...</Card>
</Columns>
```

Link the corresponding guide (from SDK page) or SDK reference (from guide page), plus a related concept or tutorial.

## Placeholder page format

```mdx theme={null}
<Note>
This page is a placeholder. Full documentation is coming soon.
</Note>

[One sentence of what this page will cover]

Topics this page will cover:
- bullet list of planned content
```

If the placeholder represents an unsupported public feature, decide `noindex: true` case by case based on product intent. Some coming-soon pages should remain indexable when they help explain the public roadmap or current product boundary.

## Canonical agent list

Always list agents explicitly — never truncate or say "and more":

**Claude Code** (Anthropic), **Gemini CLI** (Google), **GitHub Copilot** (Microsoft), **Cursor** (Anysphere), **Devin** (Cognition AI), **OpenAI Codex** (OpenAI), **Aider** (open-source), **Amp** (Sourcegraph — NOT "Amp Code"), **OpenCode** (open-source), **Windsurf** (Codeium, uses `.windsurfrules`), **Cline** (VS Code extension, uses `.clinerules`), **Continue** (open-source VS Code/JetBrains), **Antigravity**, **Kiro**, and all other AI coding agents.

## CLI — verified commands only

Verify all CLI commands against `edge-spark/cli/src/commands/` before documenting. Never guess. If `edge-spark/` is empty, run `git submodule update --init`.

**Implemented and verified:**

```
npm install -g @edgespark/cli
edgespark init [name] [--agent claude|gemini|codex] [--scaffold]
edgespark deploy [--dry-run]
edgespark log tail
edgespark pull
edgespark pull schema
edgespark pull types [--check]
edgespark db generate [--name <name>]
edgespark db migrate [--confirm-dangerous]
edgespark db check
edgespark db studio [--port <port>] [--host <host>]
edgespark db sql <query> [--confirm-dangerous]
edgespark storage apply [--confirm-dangerous]
edgespark storage bucket list [--desc]
edgespark secret list
edgespark secret set <keys...>
edgespark secret delete <keys...>
edgespark var list
edgespark var set <entries...>
edgespark var delete <keys...>
edgespark auth get [--json]
edgespark auth pull
edgespark auth apply
edgespark login / logout / whoami
```

**Important:** Public docs should treat `--agent` as required in all `edgespark init` examples. The current mapping is `claude -> CLAUDE.md`, `gemini -> GEMINI.md`, `codex -> AGENTS.md`, and every other agent name also falls back to `AGENTS.md`. For GitHub Copilot, Cursor, OpenCode, Amp, Devin, Aider, Windsurf, Cline, Continue, Antigravity, Kiro, and all other agents, document the real agent name in `--agent`, not `codex`.
**Important:** `edgespark pull schema` is for platform-managed system schema only. App tables live in `server/src/defs/db_schema.ts` and use `edgespark db generate` + `edgespark db migrate`.
**Important:** Public docs must match the currently exposed product surface. Even if code paths exist for future environment features, document new projects as having one default production environment today. Do not document staging URLs or `edgespark deploy promote` until that workflow is publicly available.

**NOT implemented — never document as available:**

* `edgespark mcp` → no MCP server exists yet
* `edgespark run` → source exists but it is not registered in the CLI command registry
* `edgespark storage bucket create` → removed; use `server/src/defs/storage_schema.ts` plus `edgespark storage apply`

**Public agent integration surface — keep docs aligned with `edge-spark/web` and the checked-in plugin manifests:**

* Claude Code plugin: `claude plugin marketplace add edgesparkhq/claude-plugins` then `claude plugin install edgespark@edgespark-claude-plugins`
* Gemini CLI extension: `gemini extensions install https://github.com/edgesparkhq/gemini-extensions`
* Codex plugin: open `codex` and paste the install prompt from `web/src/components/terminal-prompt.tsx`
* Cursor plugin: in Cursor Agent chat run `/add-plugin edgespark@https://github.com/edgesparkhq/cursor-plugins` (requires Cursor 2.5 or later)
* GitHub Copilot plugin: `copilot plugin marketplace add edgesparkhq/copilot-plugins` then `copilot plugin install edgespark@edgespark-copilot-plugins`
* Generic agent skills: `npx skills add edgesparkhq/agent-skills`
* EdgeSpark docs MCP helper: `npx add-mcp https://mcp.edgespark.dev/docs`

Keep the docs' agent support story consistent with the public onboarding in `edge-spark/web`: EdgeSpark supports **all AI coding agents**. The public setup surface currently has six paths: **Claude Code**, **OpenAI Codex**, **Gemini CLI**, **Cursor**, **GitHub Copilot**, and **all other AI coding agents**. The first five are dedicated plugin or extension flows; the last path is the generic skills + docs MCP + `AGENTS.md` flow for everything else.

## Current scaffold facts

* `edgespark init` now creates a fullstack project with root `server/`, `web/`, `configs/`, and `edgespark.toml`
* Root `package.json` is not a workspace; install dependencies separately in `server/` and `web/`
* Server entry point is `server/src/index.ts` and should `export default app`
* Frontend browser SDK in the scaffold is `@edgespark/web` from `web/src/lib/edgespark.ts`
* Public browser SDK docs must follow `edge-spark/sdk/web-client-v2/` and the scaffolded `web/src/lib/edgespark.ts`, not the legacy `edge-spark/sdk/web-client/` package
* Repo-authored app schema lives in `server/src/defs/db_schema.ts`
* Repo-authored bucket declarations live in `server/src/defs/storage_schema.ts`
* Runtime keys for vars and secrets live in `server/src/defs/runtime.ts`
* Generated files live in `server/src/__generated__/`
* Runtime imports come from `edgespark` and `edgespark/http`, not from a user-created client factory
* Mint preview should ignore the `edge-spark/` submodule via `.mintignore`; otherwise local preview gets noisy and can hide real doc issues
* Agent docs should default to seamless autonomous flow. Do not tell agents to stop for routine coding, schema/config updates, migrations, tests, logs, or normal deploys. Stop only for login, secret entry, or clearly destructive actions.

## SEO and GEO

* Real SEO signals: `title` (primary ranking factor), `description` (CTR), body text with agent names in headings and prose
* GEO (LLM discoverability): Mintlify auto-generates `llms.txt` and `llms-full.txt` from page content. Agent names in prose get indexed by LLMs. `docs.json` must have `"indexing": "all"`.
* `keywords` frontmatter has no Google ranking value — keep it for Mintlify internal search only
* `docs.json.name` controls the browser tab suffix site-wide. Keep it descriptive, such as `EdgeSpark Documentation`, so homepage titles do not collapse into duplicates like `EdgeSpark - EdgeSpark`
* Favor distinct, query-matching page titles over generic labels like `Quickstart` or `Testing`. Use `sidebarTitle` when you need a shorter navigation label than the SEO-facing page title
* For high-traffic landing pages and hub pages, aim for roughly 50–60 character titles and 140–160 character descriptions when the wording still reads naturally. Prefer explicit query phrases like `EdgeSpark CLI`, `AI coding agents`, `Cloudflare`, `Hono`, `D1`, `R2`, and `auth` over vague labels.
* For agent setup pages, only claim auto-loading or default rule-file behavior when it is verified by the current public onboarding or an explicit product surface. Otherwise say the agent "uses" the generated instructions file and keep the statement scoped to EdgeSpark's side of the integration.

## Git workflow

* Never use `--no-verify` or skip pre-commit hooks
* Commit frequently with descriptive messages
* Work on the current branch unless instructed otherwise