Skip to main content

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.

​
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: 
<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

<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
Last modified on May 6, 2026