{
  "id": "2026-05-06-personal-brain-recipe-design-5f78e24528",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/superpowers/specs/2026-05-06-personal-brain-recipe-design.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.774Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Personal Brain Capability Recipe Design",
  "summary": "Personal Brain Capability Recipe Design Purpose Create the first URL addressable capability recipe: a Codex buildable personal brain app. A first time Codex user should be able to paste a recipe URL into Codex and get a working local app without making architecture decisions. The recipe demonstrates the larger capability marketplace thesis: a recipe is not a...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Purpose",
      "level": 2,
      "body": "Create the first URL-addressable capability recipe: a Codex-buildable personal brain app. A first-time Codex user should be able to paste a recipe URL into Codex and get a working local app without making architecture decisions.\n\nThe recipe demonstrates the larger capability marketplace thesis: a recipe is not a package install or static template. It is an agent-executable blueprint that tells Codex what to build, how to configure it, and how to prove it works."
    },
    {
      "title": "Product Definition",
      "level": 2,
      "body": "The V1 recipe builds a local personal brain web app connected to a Bezel hosted Supabase sandbox by default. The hosted sandbox lives in the Bezel Projects Supabase database, not the RedKey operating database.\n\nThe app lets a user:\n\n- Capture thoughts.\n- View all submitted thoughts.\n- Promote thoughts into ideas.\n- Promote thoughts or ideas into suggested tasks.\n- Accept suggested tasks into a simple Kanban board.\n- Preserve source evidence from each idea or task back to its originating thought.\n\nThe V1 app is intentionally small. It proves the core loop:\n\n```text\nRecipe URL -> Codex build -> local app -> hosted brain -> thoughts -> ideas -> tasks -> Kanban\n```"
    },
    {
      "title": "Target User",
      "level": 2,
      "body": "The target user is not a developer. They may have installed Codex for the first time and may not know Supabase, SQL, migrations, npm, environment variables, Git, or deployment.\n\nThe expected starting prompt is:\n\n```text\nBuild this: https://recipes.bezeliq.ai/personal-brain\n```\n\nCodex should then fetch the recipe and guide the user with one plain-English question at a time."
    },
    {
      "title": "Recipe Delivery Model",
      "level": 2,
      "body": "The recipe is URL-first.\n\nThe public recipe URL should provide:\n\n- A human-readable page explaining what will be built.\n- A machine-readable manifest at `recipe.json`.\n- Markdown instructions for Codex.\n- App specifications.\n- Schema and API contracts.\n- Seed/demo data.\n- Acceptance tests.\n- Troubleshooting guidance.\n\nRecommended URL shape:\n\n```text\nhttps://recipes.bezeliq.ai/personal-brain\nhttps://recipes.bezeliq.ai/personal-brain/recipe.json\nhttps://recipes.bezeliq.ai/personal-brain/START_HERE.md\nhttps://recipes.bezeliq.ai/personal-brain/codex-instructions.md\n```"
    },
    {
      "title": "Golden Path",
      "level": 2,
      "body": "V1 has one default path: Bezel hosted Supabase sandbox in the Bezel Projects Supabase database.\n\nCodex should:\n\n1. Fetch the recipe.\n2. Explain that it will build a local personal brain app.\n3. Ask what the user wants to call their brain.\n4. Use the Bezel hosted sandbox by default.\n5. Scaffold the local app.\n6. Connect the app to the hosted sandbox namespace.\n7. Seed demo thoughts if the user agrees.\n8. Build Thoughts, Ideas, and Tasks boards.\n9. Run acceptance checks.\n10. Start the local app and give the user the localhost URL.\n\nCodex should not ask the user to choose a database, framework, migration strategy, or deployment target in V1."
    },
    {
      "title": "Execution Contract",
      "level": 2,
      "body": "This section removes implementation discretion from the recipe. Codex can improve details inside the selected stack, but it should not choose a different architecture unless the local environment makes the golden path impossible."
    },
    {
      "title": "Default Stack",
      "level": 3,
      "body": "The V1 recipe builds:\n\n- Next.js App Router application.\n- TypeScript.\n- Supabase JavaScript client.\n- Plain CSS modules or a minimal local stylesheet.\n- Local development via `npm run dev`.\n- Verification via `npm run build` and a small smoke test script.\n\nThe recipe should avoid heavy UI frameworks and package choices that increase setup friction. The generated app should be understandable as ordinary web app code."
    },
    {
      "title": "Hosted Sandbox Access",
      "level": 3,
      "body": "The hosted sandbox must not expose a shared unrestricted Supabase service key to the generated app.\n\nThe hosted V1 sandbox uses pre-created tables in the Bezel Projects Supabase database. Codex must not run migrations against the hosted sandbox, and the generated local app must not receive credentials capable of creating or altering tables.\n\nV1 should use a Bezel-issued sandbox configuration:\n\n- `BEZEL_BRAIN_API_URL`\n- `BEZEL_BRAIN_PUBLIC_KEY`\n- `BEZEL_BRAIN_INSTALL_TOKEN`\n- `BEZEL_BRAIN_NAMESPACE`\n\nThe install token identifies the sandbox brain namespace and is used only by the local app/API during setup. The app should store user data under the assigned namespace.\n\nFor the first internal recipe demo, these values can be provided by a `.env.local` template or copied from a Bezel-controlled setup page. The public recipe must state that production users should not paste private personal data into the hosted sandbox until Bezel publishes clear privacy, export, and deletion terms."
    },
    {
      "title": "Namespace and Identity",
      "level": 3,
      "body": "V1 does not require full user auth.\n\nThe app should create or use one namespace:\n\n- `brain_id`: stable identifier for this local brain.\n- `brain_name`: user-visible name.\n- `install_token_hash`: server-side reference, never displayed after setup.\n\nAll rows must include `brain_id`. Queries must filter by `brain_id`.\n\nV2 can replace this with Supabase Auth and row-level security. V1 should still model `brain_id` explicitly so migration to private Supabase is straightforward."
    },
    {
      "title": "Recipe Manifest Contract",
      "level": 3,
      "body": "`recipe.json` is the machine-readable entry point Codex should read first.\n\nMinimum manifest shape:\n\n```json\n{\n  \"schema_version\": \"0.1\",\n  \"recipe_id\": \"personal-brain-supabase\",\n  \"name\": \"Personal Brain\",\n  \"default_mode\": \"bezel_hosted_sandbox\",\n  \"target_user\": \"first_time_codex_user\",\n  \"stack\": {\n    \"app\": \"nextjs\",\n    \"language\": \"typescript\",\n    \"database\": \"supabase_hosted_sandbox\"\n  },\n  \"entrypoints\": {\n    \"human\": \"START_HERE.md\",\n    \"codex\": \"codex-instructions.md\",\n    \"acceptance\": \"app-spec/acceptance.md\"\n  },\n  \"build_outputs\": [\n    \"local_web_app\",\n    \"thoughts_board\",\n    \"idea_board\",\n    \"kanban_board\",\n    \"hosted_sandbox_connection\"\n  ],\n  \"verification\": {\n    \"install\": \"npm install\",\n    \"build\": \"npm run build\",\n    \"smoke\": \"npm run smoke\"\n  }\n}\n```\n\nThe manifest should include file checksums or version identifiers once recipes are hosted publicly."
    },
    {
      "title": "Build Steps",
      "level": 3,
      "body": "Codex should follow these steps:\n\n1. Read `recipe.json`.\n2. Read `START_HERE.md` and `codex-instructions.md`.\n3. Create the local app files.\n4. Create `.env.local.example`.\n5. Ask for the brain name.\n6. Create or configure `brain_id`.\n7. Connect to hosted sandbox using the provided sandbox configuration.\n8. Create local data-access helpers that always filter by `brain_id`.\n9. Build the Home, Capture, Thoughts, Ideas, Tasks, and Settings screens.\n10. Add demo seed data if the user accepts.\n11. Run build and smoke verification.\n12. Start the local app."
    },
    {
      "title": "Verification Commands",
      "level": 3,
      "body": "The recipe must provide concrete commands:\n\n```bash\nnpm install\nnpm run build\nnpm run smoke\nnpm run dev\n```\n\n`npm run smoke` should verify at least:\n\n- app can load configuration\n- hosted sandbox connection responds\n- seeded or created thought is readable\n- idea can link to source thought\n- suggested task can link to source thought or idea\n- task status can move through the Kanban statuses\n\nIf the sandbox is unavailable, the smoke test should fail with a plain-English message that names the missing configuration or connection failure."
    },
    {
      "title": "Storage Model",
      "level": 2,
      "body": "V1 uses the Bezel hosted Supabase sandbox as the default storage layer.\n\nThis is the fastest path because the user does not need a Supabase account or project.\n\nHosted V1 storage is in the Bezel Projects Supabase database. RedKey remains the internal operating/orchestration system and must not be used as the hosted personal brain sandbox.\n\nThe app should make the storage mode visible in Settings:\n\n- Mode: Bezel Hosted Sandbox\n- Brain name\n- User namespace/profile identifier\n- Export option placeholder\n- Future private Supabase migration note\n\nThe design must not lock users into hosted storage. V2 will support private Supabase installs using the same conceptual data model."
    },
    {
      "title": "Privacy and Portability Boundary",
      "level": 3,
      "body": "The hosted sandbox is for fast setup and early demos. The app must clearly tell the user:\n\n- This V1 stores data in a Bezel-hosted Supabase sandbox.\n- Do not store sensitive personal data until the hosted privacy and deletion terms are explicit.\n- The user should be able to export their rows.\n- Private Supabase install is the long-term ownership path.\n\nV1 Settings should include visible placeholders for:\n\n- Export data.\n- Delete sandbox data.\n- Migrate to private Supabase.\n\nIf export/delete are not implemented in the first generated app, they must be labeled as unavailable in V1 rather than implied as working."
    },
    {
      "title": "Home",
      "level": 3,
      "body": "The app landing screen. It should show the most important current state:\n\n- Quick capture.\n- Recent thoughts.\n- New ideas.\n- Suggested tasks.\n- Active and waiting tasks."
    },
    {
      "title": "Capture",
      "level": 3,
      "body": "A simple thought entry surface:\n\n- Title, optional.\n- Body/content.\n- Save to brain.\n- After save, offer promotion actions.\n\nV1 can use text input only. Voice, pasted email, meeting transcripts, and AI chat MCP capture are deferred."
    },
    {
      "title": "Thoughts Board",
      "level": 3,
      "body": "All submitted brain items.\n\nEach thought card should show:\n\n- Title or generated first-line label.\n- Short excerpt.\n- Created date.\n- Promotion actions.\n- Linked ideas/tasks created from it."
    },
    {
      "title": "Idea Board",
      "level": 3,
      "body": "Ideas created from thoughts.\n\nEach idea card should show:\n\n- Title.\n- Summary.\n- Source thought evidence.\n- Status: new, developing, archived.\n- Action to create suggested task."
    }
  ],
  "html_path": "artifacts/2026-05-06-personal-brain-recipe-design-5f78e24528.html",
  "json_path": "artifacts/2026-05-06-personal-brain-recipe-design-5f78e24528.json"
}