diff --git a/AGENTS.md b/AGENTS.md
index 98957729c6c4..3c25c3ac804d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -161,3 +161,105 @@ status: accepted   # decisions only
 
 `icon:` is a single emoji and shows on the page in the web app. Keep the emoji out of the title.
 <!-- craftspace:end -->
+
+<!-- craftspace:brain-guide v7 -->
+
+## Craftspace brain
+
+This repo carries its own brain. Durable context lives in `brain/knowledge/` and syncs into Craftspace, so
+what you write here is what the team reads there.
+
+**Read it before you answer.** How this project works, its decisions, its vocabulary and its gotchas are
+already written down. Grep `brain/knowledge/` first: it is the same context Craftspace serves over MCP, with no setup,
+and current to the working tree.
+
+- `brain/knowledge/` is the whole tree, one folder per page. `brain/knowledge/<area>/index.md` is the page for
+  `<area>`, and a leaf file beside it is that page's child.
+- `brain/knowledge/decisions/` holds one hard-to-reverse call per file, newest number last.
+
+**Write back what will still help a teammate next month**, and only that: a decision and its why, a gotcha,
+a procedure that worked. Skip the ephemeral, meaning flaky one-off transients, generic tooling knowledge,
+and another project's facts. A learning left in your session is lost to the team.
+
+Write a markdown FILE. Do not call the Craftspace `upsert_*` tools from this repo: a file rides your pull
+request and gets reviewed, an MCP write pushes straight to the default branch and skips that review.
+
+Pick the file by the shape of what you learned:
+
+| What you learned | Where it goes |
+| --- | --- |
+| A hard-to-reverse call and its why | `brain/knowledge/decisions/<slug>.md` |
+| A repeatable procedure | `brain/knowledge/<area>/<slug>.md`, written as the steps |
+| A gotcha or a how-it-works fact | a bullet under `Gotchas` on the page for that feature |
+| A genuinely new topic | `brain/knowledge/<slug>.md` |
+| A dated one-off with nothing to teach | one line in `brain/knowledge/memory.md` |
+
+`<slug>` is lowercase, with each run of non-alphanumeric characters collapsed to one `-`.
+
+**A gotcha is not a page.** Add it under the `Gotchas` heading of the page for the feature it bites, so
+whoever reads about that feature meets it in place instead of having to know it exists. Same for any other
+fact about something that already exists. Start a new file only when the TOPIC is new.
+
+The filename is the entry's identity, so grep `brain/knowledge/` first and edit the file that already covers the
+topic. A differently named second file is a duplicate, not an update.
+
+Frontmatter every file understands:
+
+~~~
+---
+title: Optional, overrides the H1
+icon: 🧭
+status: accepted   # decisions only
+---
+~~~
+
+`icon:` is a single emoji and shows on the page in Craftspace. Keep the emoji out of the title.
+
+### Decisions
+
+Only offer one when all three hold: it is **hard to reverse**, it is **surprising without context**, and
+it came from a **real trade-off**. Miss any one and skip it. Easy to reverse? You will just reverse it.
+Not surprising? Nobody will wonder why. No real alternative? There is nothing to record.
+
+Title it as the claim itself, so the list reads as a set of positions:
+
+~~~
+Worker is the Sandbox
+Pieces are distributed as links, resolved lazily
+~~~
+
+The body is four `## ` sections — **Decision**, **Context**, **Why** (the reasoning and the main rejected
+alternative), **Consequences** — a sentence or two each. Frontmatter takes `status: accepted`, or
+`proposed` while the call is still open and `superseded by <slug>` once it is not.
+
+### Area pages
+
+The wiki is flat and **one Area owns exactly one page**: Title Case, an emoji icon, and everything known
+about that Area on it. The page is a **glossary spine**, one line per term, and any term that outgrows a
+line **graduates** to its own small child page.
+
+~~~
+# Execution Runtime
+Two sentences: what this Area is.
+
+**Worker** — definition. _Avoid_: "pool" (retired alias)
+**Sandbox** — definition, see *sandbox*
+
+## Key files
+- `packages/server/worker` — the run loop
+~~~
+
+Be opinionated: one canonical word per concept, every retired alias on an `_Avoid_` line. Keep each
+definition to a sentence or two, saying what the thing IS rather than what it does. Only terms specific to
+this company belong; general programming words do not, however often the team says them. Never mirror the
+public docs, link to them.
+
+A page backed by code ends in `## Key files`. **Directories, not files**, wherever a directory covers it,
+and **never line numbers** — any edit above one silently invalidates it. Name the entry-point symbol when
+there is one; it survives a file move, which no path does. Only add paths the team actually knows: a
+guessed path reads as authoritative and sends the next agent to the wrong place.
+
+Keep every write short and human, a few tight sentences or a short list, never an essay. The brain is
+skimmed, not read.
+
+<!-- /craftspace:brain-guide -->
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 120000
index 47dc3e3d863c..000000000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1 +0,0 @@
-AGENTS.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000000..3c25c3ac804d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,265 @@
+# Activepieces
+
+Open-source AI-first workflow automation platform. Self-hosted or cloud. 400+ pieces. MCP support.
+
+## Architecture (Non-Obvious Rules)
+
+- **Multi-tenant**: Platform → Projects → Users. ALL queries MUST filter by `projectId` or `platformId`.
+- **Editions**: CE (`ce`), EE (`ee`), Cloud (`cloud`) via `AP_EDITION`. EE extends CE via `hooksFactory` — **never import `src/app/ee/` in CE code**.
+- **Feature gating**: `platformMustHaveFeatureEnabled((p) => p.plan.myFlag)` on EE modules.
+- **Entity registration**: New entities MUST be added to `getEntities()` in `database-connection.ts` — TypeORM does NOT auto-discover.
+- **HTTP**: `POST` for all create/update mutations. `DELETE` for deletes. Never PUT/PATCH.
+- **Security**: Every endpoint needs `securityAccess` config.
+- **Side effects**: Separated into `*-side-effects.ts` files, called explicitly after mutations.
+- **Multi-server**: Use `distributedLock`, BullMQ deduplication, or `FOR UPDATE SKIP LOCKED` for concurrent operations.
+- **Managed PostgreSQL**: No custom extensions. Use `sanitizeObjectForPostgresql()` for external data.
+- **Before modifying a module**: Read its subsystem page in `brain/<area>/` (and that area's `index.md` glossary) for domain language, entities, services, and integration details.
+- **Cross-cutting libraries live in `packages/core/*`**, ordered thin → thick: `core-utils`, `core-piece-types`, `core-formula`, `core-execution` (thin, bundleable, framework-agnostic) and `core/shared` (the one thick, app-level member — **keeps the name `@activepieces/shared`**, carries DB/EE/management schemas + heavy deps). Pieces and the engine may import the thin members but **never** `@activepieces/shared`; pieces get what they need via `@activepieces/pieces-framework`. See `.claude/rules/core-packages.md`.
+| `brain/<area>/index.md` | 9 areas | First stop for an unfamiliar subsystem | Area glossary + list of its pages |
+| `brain/<area>/*.md` | one page per subsystem | When Claude explores that subsystem | Entity schemas, services, data flows, gotchas |
+| `brain/decisions/*.md` | numbered, under `decisions/` | When Claude needs the *why* behind a design | One hard-to-reverse call each |
+| `.claude/rules/` | 3-5 lines each | Every session | Critical safety checks (entity registration, data isolation, edition safety) |
+| `.agents/skills/` | one folder each | When invoked | Investigations, not conventions — `/debug-failed-run`, `/triage-*`, `/piece-builder`. Code shapes and conventions live in the wiki, not here. |
+- **Exported types and constants must be placed at the end of the file**, after all logic (functions, hooks, components, classes, etc.). This keeps the logic front and centre when reading a file, and groups the public contract at a predictable location.
+
+  ```ts
+  // ✅ Correct
+  function doSomething() { ... }
+
+  export const MY_CONST = 'value';
+  export type MyType = { ... };
+  // ✅ Correct
+  const businessService = () => { ... }
+
+  export const MY_CONST = 'value';
+  export type MyType = { ... };
+
+  // ❌ Wrong — types/consts mixed in before logic
+  export const MY_CONST = 'value';
+  export type MyType = { ... };
+  function doSomething() { ... }
+  ```
+
+## Coding Conventions
+
+- **npm dependencies go in the workspace that imports them, never the root `package.json`** — every workspace (api, worker, web, each piece, …) must declare what its own code imports, in its own `package.json` (`dependencies` for runtime imports, `devDependencies` for test/tooling-only). Bun's isolated linker resolves each workspace from its own manifest, and the Docker image installs only workspace manifests — an undeclared import that "works locally" will crash the production container. Root `dependencies` is only `jsonwebtoken` (required by `docker-entrypoint.sh`); root `devDependencies` is only for repo-level tooling under `scripts/` and `tools/`. Pin exact versions like the surrounding entries, and run `bun install` afterwards so `bun.lock` stays in sync.
+- **No `any` type** — Use proper type definitions or `unknown` with type guards
+- **No type casting** — Do not use `as SomeType` to force types. If you encounter an unnecessary cast, remove it.
+- **No deprecated APIs** — Before using any library method or export, check its JSDoc. If it carries a `@deprecated` tag, use the recommended replacement instead. Examples: prefer `z.enum` over `z.nativeEnum`.
+- **Go-style error handling** — Use `tryCatch` / `tryCatchSync` from `@activepieces/shared`
+- **Zod error messages must be i18n keys** — Every `.min()`, `.refine()`, `.superRefine()`, etc. that surfaces a user-facing message must pass a string that exists as a key in `packages/web/public/locales/en/translation.json`. For common messages (e.g. required fields) use the `formErrors` constant from `@activepieces/shared`. Add a new translation key if none fits; never use raw English sentences that are not in the translation file.
+- **`@activepieces/shared` version bump** — Any change to `packages/core/shared` must be accompanied by a version bump in `packages/core/shared/package.json`: bump the **patch** version for non-breaking additions or fixes, bump the **minor** version for new exports or behaviour changes after you check if it has already been bumped in the current branch or not
+- **Helper functions** — Define non-exported helpers outside of const declarations
+- **Named parameters** — Always use a single destructured object parameter instead of positional arguments. This applies to every function with more than one parameter, regardless of type. It prevents mix-ups at the call site and makes future additions non-breaking.
+- **Prefer immutable data flow** — Functions should produce data by returning it, not by mutating an array/object the caller passes in. If a helper accumulates results (logs, derived rows, computed bindings), it should build the collection locally and return it — not take a pre-allocated bag the caller will read after. Local mutation inside a function's own body is fine; mutation that crosses the function boundary is not. Build new collections with `.map` / `.filter` / `.reduce` / spread rather than in-place `push` / `splice` / property assignment when feasible.
+- **File order**: Imports → Exported functions/constants → Helper functions → Types
+- **Comments** — Do NOT include comments in code. No inline comments, no explanatory comment blocks, no JSDoc narration. Code must be self-explanatory through naming and structure. If a *why* genuinely needs recording, put it in the commit message or PR description, not in the source.
+- **Util file exports** — When a util file exposes multiple plain functions or constants (non-React), do not export them individually. Instead, group them into a single named `const` and export that one object (e.g. `export const myUtils = { fn1, fn2 }`). Callers use `myUtils.fn1()` at the call site. **React components** in the same file should be **named exports** (e.g. `export function MyAlert()` or `export const MyAlert = …`) and imported by name — do not bundle them into a wrapper object for the sake of this rule.
+- **Safe outbound HTTP (SSRF)** — For any outbound HTTP in `packages/server/{api,worker,utils}`, use `safeHttp.axios` / `safeHttp.createAxios({ ... })` from `@activepieces/server-utils`. Never use raw `fetch` or `axios.create` for URLs that come from user input, admin config, OAuth endpoints, or third-party integrations — they bypass the SSRF filter (private/loopback/metadata IPs). See `.claude/rules/safe-http.md`.
+
+## Query Error Handling
+
+- **Global error dialog via `meta`** — `app.tsx` has a `QueryCache.onError` handler that shows an error dialog when `query.meta?.showErrorDialog` is truthy. When adding a new `useQuery` that fetches primary page data (e.g. table rows, list data), add `meta: { showErrorDialog: true }` to the query options.
+- **Do NOT add** `showErrorDialog` to minor/auxiliary queries (feature flags, piece metadata, single-item fetches, filter options, user details). These should fail silently.
+- Rule of thumb: if the query failure would leave the user staring at an empty table or blank page with no explanation, it should have `meta: { showErrorDialog: true }`.
+
+## Key Utilities (`@activepieces/shared`)
+
+`apId()`, `tryCatch()`, `tryCatchSync()`, `isNil()`, `spreadIfDefined()`, `spreadIfNotUndefined()`, `ActivepiecesError({ code, params })`, `SeekPage<T>`, `formErrors`, `BaseModelSchema`, `chunk()`, `partition()`, `unique()`, `omit()`, `sanitizeObjectForPostgresql()`
+
+## Testing
+
+```bash
+npm run test-unit     # Vitest: engine + shared
+npm run test-api      # API integration (CE, EE, Cloud)
+```
+API tests: `setupTestEnvironment()` + `createTestContext(app)` → `ctx.post()`, `ctx.get()`. DB auto-cleaned between tests.
+
+## Commands
+
+This monorepo uses **turbo** (see `turbo.json`). There is no Nx — never invoke `nx` or `npx nx`.
+
+```bash
+npm start                                       # Setup dev + start all
+npm run dev                                     # Frontend + backend
+npm run lint-dev                                # Lint with auto-fix (ALWAYS before done)
+npx turbo run lint --filter=<package>           # Lint a single package, e.g. --filter=web
+npx turbo run serve --filter=web -- --mode=cloud # Run local frontend against the cloud backend
+```
+
+When running in `--mode=cloud`, do not use OAuth2 connections — the OAuth provider will redirect back to `cloud.activepieces.com` after sign-in instead of your local frontend, breaking the flow. Use API-key / basic-auth connections, or test OAuth2 against a fully local backend.
+
+## Pull Requests
+
+- When creating a PR with `gh pr create`, always apply exactly one of these labels based on the nature of the change:
+  - **`🌟 feature`** — new functionality
+  - **`🐛 bug`** — bug fix
+  - **`skip-changelog`** — changes that should not appear in the changelog (docs, CI tweaks, internal refactors, etc.)
+- If the PR includes any contributions to pieces (integrations under `packages/pieces`), also add the appropriate pieces label (in addition to the primary label above):
+  - **`🧩 area/third-party-pieces`** — for third-party integrations (most pieces under `packages/pieces/community/`)
+  - **`🧩 area/core-pieces`** — for core pieces (under `packages/pieces/core/`)
+- **Always fill the "Breaking change?" section of the PR template** — tick exactly one box (the `breaking-change-check` CI job fails if it is left unedited). A change is breaking if a self-hoster or API consumer must take action: removed/renamed API fields or endpoints, dropped columns, new required fields, removed/required env vars, or default/limit/behaviour changes. If it is breaking:
+  - also apply the **`⛓️‍💥 breaking-change`** label (in addition to the primary label above), and
+  - add an entry to `docs/install/reference/breaking-changes.mdx` describing what changed and the action required. CI enforces that the label and the docs entry travel together.
+- **Non-rollbackable migrations are a separate axis** from customer-facing breaking changes: a migration that runs destructive DDL (`DROP TABLE`/`DROP COLUMN`, `ADD ... NOT NULL` without `DEFAULT`, etc.) must set `breaking = true` on the migration class — this is the rollback-safety flag (used by `rollback-migrations.ts` and the release rollback note), enforced by `check-migration-rollback.ts`. It does **not** by itself require the `⛓️‍💥 breaking-change` label; decide that from the upgrade-impact question above.
+
+## Database Migrations
+
+- Before creating or modifying a database migration, **always read the [Database Migrations Playbook](https://www.activepieces.com/docs/handbook/engineering/playbooks/database-migration#database-migrations)** first. Follow its instructions for generating and structuring migrations.
+
+## Verification
+
+- Always run `npm run lint-dev` as part of any verification step before considering a task complete.
+
+## White-Labeling & Edition Paths
+
+- **All customer-facing UI must be white-labeled.** Sign-in/signup pages, email templates, logos, and any user-visible branding must use the platform's configured appearance (name, colors, logos) — never hardcode "Activepieces" in user-facing surfaces.
+- **Test across all edition paths.** Every customer-facing feature must be verified on:
+  - **Community Edition** (self-hosted, `AP_EDITION=ce`) — no custom branding, open-source plan
+  - **Enterprise Edition** (self-hosted, `AP_EDITION=ee`) — custom branding behind `customAppearanceEnabled` flag
+  - **Cloud Freemium** (`AP_EDITION=cloud`, standard plan) — always applies platform branding
+  - **Cloud Self-Serve Paid** (`AP_EDITION=cloud`, upgraded plan) — same as freemium with higher limits
+  - **Cloud Enterprise** (`AP_EDITION=cloud`, enterprise plan) — full feature set
+- **Appearance is edition-gated.** Community always uses the default theme. Cloud always applies custom branding. Enterprise requires `platform.plan.customAppearanceEnabled`. See `packages/server/api/src/app/ee/helper/appearance-helper.ts`.
+- **Feature gating pattern:** Backend uses `platformMustHaveFeatureEnabled()` middleware (returns 402). Frontend uses `LockedFeatureGuard` component and `enabled: platform.plan.<flag>` on queries.
+
+## Useful Links
+
+- [Database Migrations Playbook](https://www.activepieces.com/docs/handbook/engineering/playbooks/database-migration)
+- [TypeORM Migrations Docs](https://orkhan.gitbook.io/typeorm/docs/migrations)
+
+<!-- craftspace:start -->
+## This repo carries its own brain
+
+Durable company context lives in `brain/` and syncs to Craftspace both ways. Read it BEFORE
+answering how this project works — its decisions, vocabulary, and gotchas are already written down.
+
+- `brain/` — the whole tree, one folder per page. `brain/area/index.md` is the page for `area`,
+  and a leaf beside it is that page's child. Grep here first.
+- `brain/decisions/` — numbered, one hard-to-reverse call each, newest number last. `index.md` is its own page.
+- `.agents/skills/` — repeatable procedures, one folder per skill (`.claude/skills` symlinks onto it).
+
+## Writing back
+
+Write a markdown FILE, do not call the Craftspace `upsert_*` tools — a file rides your PR and review,
+an MCP write pushes straight to the default branch. Edit the file that already covers the topic instead
+of adding a near-duplicate.
+
+**A gotcha is not a page.** Add it as a bullet under the `Gotchas` heading of the page for the feature it
+bites, so whoever reads about that feature meets it in place instead of having to know it exists. Same for
+any other fact about an existing feature. Start a new file only when the TOPIC is new.
+
+Frontmatter each file understands:
+
+```
+---
+title: Optional, overrides the H1
+icon: 🧭
+status: accepted   # decisions only
+---
+```
+
+`icon:` is a single emoji and shows on the page in the web app. Keep the emoji out of the title.
+<!-- craftspace:end -->
+
+<!-- craftspace:brain-guide v7 -->
+
+## Craftspace brain
+
+This repo carries its own brain. Durable context lives in `brain/knowledge/` and syncs into Craftspace, so
+what you write here is what the team reads there.
+
+**Read it before you answer.** How this project works, its decisions, its vocabulary and its gotchas are
+already written down. Grep `brain/knowledge/` first: it is the same context Craftspace serves over MCP, with no setup,
+and current to the working tree.
+
+- `brain/knowledge/` is the whole tree, one folder per page. `brain/knowledge/<area>/index.md` is the page for
+  `<area>`, and a leaf file beside it is that page's child.
+- `brain/knowledge/decisions/` holds one hard-to-reverse call per file, newest number last.
+
+**Write back what will still help a teammate next month**, and only that: a decision and its why, a gotcha,
+a procedure that worked. Skip the ephemeral, meaning flaky one-off transients, generic tooling knowledge,
+and another project's facts. A learning left in your session is lost to the team.
+
+Write a markdown FILE. Do not call the Craftspace `upsert_*` tools from this repo: a file rides your pull
+request and gets reviewed, an MCP write pushes straight to the default branch and skips that review.
+
+Pick the file by the shape of what you learned:
+
+| What you learned | Where it goes |
+| --- | --- |
+| A hard-to-reverse call and its why | `brain/knowledge/decisions/<slug>.md` |
+| A repeatable procedure | `brain/knowledge/<area>/<slug>.md`, written as the steps |
+| A gotcha or a how-it-works fact | a bullet under `Gotchas` on the page for that feature |
+| A genuinely new topic | `brain/knowledge/<slug>.md` |
+| A dated one-off with nothing to teach | one line in `brain/knowledge/memory.md` |
+
+`<slug>` is lowercase, with each run of non-alphanumeric characters collapsed to one `-`.
+
+**A gotcha is not a page.** Add it under the `Gotchas` heading of the page for the feature it bites, so
+whoever reads about that feature meets it in place instead of having to know it exists. Same for any other
+fact about something that already exists. Start a new file only when the TOPIC is new.
+
+The filename is the entry's identity, so grep `brain/knowledge/` first and edit the file that already covers the
+topic. A differently named second file is a duplicate, not an update.
+
+Frontmatter every file understands:
+
+~~~
+---
+title: Optional, overrides the H1
+icon: 🧭
+status: accepted   # decisions only
+---
+~~~
+
+`icon:` is a single emoji and shows on the page in Craftspace. Keep the emoji out of the title.
+
+### Decisions
+
+Only offer one when all three hold: it is **hard to reverse**, it is **surprising without context**, and
+it came from a **real trade-off**. Miss any one and skip it. Easy to reverse? You will just reverse it.
+Not surprising? Nobody will wonder why. No real alternative? There is nothing to record.
+
+Title it as the claim itself, so the list reads as a set of positions:
+
+~~~
+Worker is the Sandbox
+Pieces are distributed as links, resolved lazily
+~~~
+
+The body is four `## ` sections — **Decision**, **Context**, **Why** (the reasoning and the main rejected
+alternative), **Consequences** — a sentence or two each. Frontmatter takes `status: accepted`, or
+`proposed` while the call is still open and `superseded by <slug>` once it is not.
+
+### Area pages
+
+The wiki is flat and **one Area owns exactly one page**: Title Case, an emoji icon, and everything known
+about that Area on it. The page is a **glossary spine**, one line per term, and any term that outgrows a
+line **graduates** to its own small child page.
+
+~~~
+# Execution Runtime
+Two sentences: what this Area is.
+
+**Worker** — definition. _Avoid_: "pool" (retired alias)
+**Sandbox** — definition, see *sandbox*
+
+## Key files
+- `packages/server/worker` — the run loop
+~~~
+
+Be opinionated: one canonical word per concept, every retired alias on an `_Avoid_` line. Keep each
+definition to a sentence or two, saying what the thing IS rather than what it does. Only terms specific to
+this company belong; general programming words do not, however often the team says them. Never mirror the
+public docs, link to them.
+
+A page backed by code ends in `## Key files`. **Directories, not files**, wherever a directory covers it,
+and **never line numbers** — any edit above one silently invalidates it. Name the entry-point symbol when
+there is one; it survives a file move, which no path does. Only add paths the team actually knows: a
+guessed path reads as authoritative and sends the next agent to the wrong place.
+
+Keep every write short and human, a few tight sentences or a short list, never an essay. The brain is
+skimmed, not read.
+
+<!-- /craftspace:brain-guide -->
diff --git a/brain/ai-intelligence/ai-agents.md b/brain/knowledge/ai-intelligence/ai-agents.md
similarity index 100%
rename from brain/ai-intelligence/ai-agents.md
rename to brain/knowledge/ai-intelligence/ai-agents.md
diff --git a/brain/ai-intelligence/ai-mcp.md b/brain/knowledge/ai-intelligence/ai-mcp.md
similarity index 100%
rename from brain/ai-intelligence/ai-mcp.md
rename to brain/knowledge/ai-intelligence/ai-mcp.md
diff --git a/brain/ai-intelligence/ai-providers.md b/brain/knowledge/ai-intelligence/ai-providers.md
similarity index 100%
rename from brain/ai-intelligence/ai-providers.md
rename to brain/knowledge/ai-intelligence/ai-providers.md
diff --git a/brain/ai-intelligence/index.md b/brain/knowledge/ai-intelligence/index.md
similarity index 100%
rename from brain/ai-intelligence/index.md
rename to brain/knowledge/ai-intelligence/index.md
diff --git a/brain/ai-intelligence/mcp-server.md b/brain/knowledge/ai-intelligence/mcp-server.md
similarity index 100%
rename from brain/ai-intelligence/mcp-server.md
rename to brain/knowledge/ai-intelligence/mcp-server.md
diff --git a/brain/ask-tool-check.md b/brain/knowledge/ask-tool-check.md
similarity index 100%
rename from brain/ask-tool-check.md
rename to brain/knowledge/ask-tool-check.md
diff --git a/brain/connections-auth/api-keys.md b/brain/knowledge/connections-auth/api-keys.md
similarity index 100%
rename from brain/connections-auth/api-keys.md
rename to brain/knowledge/connections-auth/api-keys.md
diff --git a/brain/connections-auth/app-connections.md b/brain/knowledge/connections-auth/app-connections.md
similarity index 100%
rename from brain/connections-auth/app-connections.md
rename to brain/knowledge/connections-auth/app-connections.md
diff --git a/brain/connections-auth/ce-authentication.md b/brain/knowledge/connections-auth/ce-authentication.md
similarity index 100%
rename from brain/connections-auth/ce-authentication.md
rename to brain/knowledge/connections-auth/ce-authentication.md
diff --git a/brain/connections-auth/ee-authentication-sso-rbac.md b/brain/knowledge/connections-auth/ee-authentication-sso-rbac.md
similarity index 100%
rename from brain/connections-auth/ee-authentication-sso-rbac.md
rename to brain/knowledge/connections-auth/ee-authentication-sso-rbac.md
diff --git a/brain/connections-auth/global-connections.md b/brain/knowledge/connections-auth/global-connections.md
similarity index 100%
rename from brain/connections-auth/global-connections.md
rename to brain/knowledge/connections-auth/global-connections.md
diff --git a/brain/connections-auth/index.md b/brain/knowledge/connections-auth/index.md
similarity index 100%
rename from brain/connections-auth/index.md
rename to brain/knowledge/connections-auth/index.md
diff --git a/brain/connections-auth/managed-auth.md b/brain/knowledge/connections-auth/managed-auth.md
similarity index 100%
rename from brain/connections-auth/managed-auth.md
rename to brain/knowledge/connections-auth/managed-auth.md
diff --git a/brain/connections-auth/oauth-apps.md b/brain/knowledge/connections-auth/oauth-apps.md
similarity index 100%
rename from brain/connections-auth/oauth-apps.md
rename to brain/knowledge/connections-auth/oauth-apps.md
diff --git a/brain/connections-auth/scim.md b/brain/knowledge/connections-auth/scim.md
similarity index 100%
rename from brain/connections-auth/scim.md
rename to brain/knowledge/connections-auth/scim.md
diff --git a/brain/connections-auth/secret-managers.md b/brain/knowledge/connections-auth/secret-managers.md
similarity index 100%
rename from brain/connections-auth/secret-managers.md
rename to brain/knowledge/connections-auth/secret-managers.md
diff --git a/brain/data-storage-observability/analytics.md b/brain/knowledge/data-storage-observability/analytics.md
similarity index 100%
rename from brain/data-storage-observability/analytics.md
rename to brain/knowledge/data-storage-observability/analytics.md
diff --git a/brain/data-storage-observability/audit-logs.md b/brain/knowledge/data-storage-observability/audit-logs.md
similarity index 100%
rename from brain/data-storage-observability/audit-logs.md
rename to brain/knowledge/data-storage-observability/audit-logs.md
diff --git a/brain/data-storage-observability/file-storage.md b/brain/knowledge/data-storage-observability/file-storage.md
similarity index 100%
rename from brain/data-storage-observability/file-storage.md
rename to brain/knowledge/data-storage-observability/file-storage.md
diff --git a/brain/data-storage-observability/index.md b/brain/knowledge/data-storage-observability/index.md
similarity index 100%
rename from brain/data-storage-observability/index.md
rename to brain/knowledge/data-storage-observability/index.md
diff --git a/brain/data-storage-observability/key-value-store.md b/brain/knowledge/data-storage-observability/key-value-store.md
similarity index 100%
rename from brain/data-storage-observability/key-value-store.md
rename to brain/knowledge/data-storage-observability/key-value-store.md
diff --git a/brain/data-storage-observability/knowledge-base.md b/brain/knowledge/data-storage-observability/knowledge-base.md
similarity index 100%
rename from brain/data-storage-observability/knowledge-base.md
rename to brain/knowledge/data-storage-observability/knowledge-base.md
diff --git a/brain/data-storage-observability/tables.md b/brain/knowledge/data-storage-observability/tables.md
similarity index 100%
rename from brain/data-storage-observability/tables.md
rename to brain/knowledge/data-storage-observability/tables.md
diff --git a/brain/decisions/000001-worker-is-the-sandbox-one-job-per-worker-scale-by-replicas.md b/brain/knowledge/decisions/000001-worker-is-the-sandbox-one-job-per-worker-scale-by-replicas.md
similarity index 100%
rename from brain/decisions/000001-worker-is-the-sandbox-one-job-per-worker-scale-by-replicas.md
rename to brain/knowledge/decisions/000001-worker-is-the-sandbox-one-job-per-worker-scale-by-replicas.md
diff --git a/brain/decisions/000002-transitional-multi-box-concurrency-honor-ap-worker-concurrency.md b/brain/knowledge/decisions/000002-transitional-multi-box-concurrency-honor-ap-worker-concurrency.md
similarity index 100%
rename from brain/decisions/000002-transitional-multi-box-concurrency-honor-ap-worker-concurrency.md
rename to brain/knowledge/decisions/000002-transitional-multi-box-concurrency-honor-ap-worker-concurrency.md
diff --git a/brain/decisions/000003-engine-posts-run-time-callbacks-directly-to-the-app.md b/brain/knowledge/decisions/000003-engine-posts-run-time-callbacks-directly-to-the-app.md
similarity index 100%
rename from brain/decisions/000003-engine-posts-run-time-callbacks-directly-to-the-app.md
rename to brain/knowledge/decisions/000003-engine-posts-run-time-callbacks-directly-to-the-app.md
diff --git a/brain/decisions/000005-freeze-piece-versions-in-the-flow-bundle-manifest.md b/brain/knowledge/decisions/000005-freeze-piece-versions-in-the-flow-bundle-manifest.md
similarity index 100%
rename from brain/decisions/000005-freeze-piece-versions-in-the-flow-bundle-manifest.md
rename to brain/knowledge/decisions/000005-freeze-piece-versions-in-the-flow-bundle-manifest.md
diff --git a/brain/decisions/000006-pieces-are-distributed-as-links-resolved-lazily.md b/brain/knowledge/decisions/000006-pieces-are-distributed-as-links-resolved-lazily.md
similarity index 100%
rename from brain/decisions/000006-pieces-are-distributed-as-links-resolved-lazily.md
rename to brain/knowledge/decisions/000006-pieces-are-distributed-as-links-resolved-lazily.md
diff --git a/brain/decisions/000007-piece-set-visibility-is-derived-at-read-time.md b/brain/knowledge/decisions/000007-piece-set-visibility-is-derived-at-read-time.md
similarity index 100%
rename from brain/decisions/000007-piece-set-visibility-is-derived-at-read-time.md
rename to brain/knowledge/decisions/000007-piece-set-visibility-is-derived-at-read-time.md
diff --git a/brain/decisions/000008-streaming-file-writes-go-through-the-app-one-path.md b/brain/knowledge/decisions/000008-streaming-file-writes-go-through-the-app-one-path.md
similarity index 100%
rename from brain/decisions/000008-streaming-file-writes-go-through-the-app-one-path.md
rename to brain/knowledge/decisions/000008-streaming-file-writes-go-through-the-app-one-path.md
diff --git a/brain/decisions/000009-approval-links-require-a-post-confirmation-on-a-dedicated-route.md b/brain/knowledge/decisions/000009-approval-links-require-a-post-confirmation-on-a-dedicated-route.md
similarity index 100%
rename from brain/decisions/000009-approval-links-require-a-post-confirmation-on-a-dedicated-route.md
rename to brain/knowledge/decisions/000009-approval-links-require-a-post-confirmation-on-a-dedicated-route.md
diff --git a/brain/decisions/000010-async-webhook-ack-is-redis-durable-not-postgres-durable.md b/brain/knowledge/decisions/000010-async-webhook-ack-is-redis-durable-not-postgres-durable.md
similarity index 100%
rename from brain/decisions/000010-async-webhook-ack-is-redis-durable-not-postgres-durable.md
rename to brain/knowledge/decisions/000010-async-webhook-ack-is-redis-durable-not-postgres-durable.md
diff --git a/brain/decisions/000011-webhook-files-stream-to-s3-by-dropping-global-multipart-buffering.md b/brain/knowledge/decisions/000011-webhook-files-stream-to-s3-by-dropping-global-multipart-buffering.md
similarity index 100%
rename from brain/decisions/000011-webhook-files-stream-to-s3-by-dropping-global-multipart-buffering.md
rename to brain/knowledge/decisions/000011-webhook-files-stream-to-s3-by-dropping-global-multipart-buffering.md
diff --git a/brain/decisions/000013-active-user-seat-floor-is-enforced-db-authoritatively.md b/brain/knowledge/decisions/000013-active-user-seat-floor-is-enforced-db-authoritatively.md
similarity index 100%
rename from brain/decisions/000013-active-user-seat-floor-is-enforced-db-authoritatively.md
rename to brain/knowledge/decisions/000013-active-user-seat-floor-is-enforced-db-authoritatively.md
diff --git a/brain/decisions/000013-sandbox-pool-is-a-pure-execute-cloud-run-pool-superseded.md b/brain/knowledge/decisions/000013-sandbox-pool-is-a-pure-execute-cloud-run-pool-superseded.md
similarity index 100%
rename from brain/decisions/000013-sandbox-pool-is-a-pure-execute-cloud-run-pool-superseded.md
rename to brain/knowledge/decisions/000013-sandbox-pool-is-a-pure-execute-cloud-run-pool-superseded.md
diff --git a/brain/decisions/000014-action-runs-dispatch-as-synchronous-user-interaction-jobs.md b/brain/knowledge/decisions/000014-action-runs-dispatch-as-synchronous-user-interaction-jobs.md
similarity index 100%
rename from brain/decisions/000014-action-runs-dispatch-as-synchronous-user-interaction-jobs.md
rename to brain/knowledge/decisions/000014-action-runs-dispatch-as-synchronous-user-interaction-jobs.md
diff --git a/brain/decisions/000014-pending-invitations-reserve-seats.md b/brain/knowledge/decisions/000014-pending-invitations-reserve-seats.md
similarity index 100%
rename from brain/decisions/000014-pending-invitations-reserve-seats.md
rename to brain/knowledge/decisions/000014-pending-invitations-reserve-seats.md
diff --git a/brain/decisions/000014-streaming-file-inputs-resolve-to-a-lazy-apstreamingfile.md b/brain/knowledge/decisions/000014-streaming-file-inputs-resolve-to-a-lazy-apstreamingfile.md
similarity index 100%
rename from brain/decisions/000014-streaming-file-inputs-resolve-to-a-lazy-apstreamingfile.md
rename to brain/knowledge/decisions/000014-streaming-file-inputs-resolve-to-a-lazy-apstreamingfile.md
diff --git a/brain/decisions/000015-jit-provisioning-plans-imply-unlimited-seats.md b/brain/knowledge/decisions/000015-jit-provisioning-plans-imply-unlimited-seats.md
similarity index 100%
rename from brain/decisions/000015-jit-provisioning-plans-imply-unlimited-seats.md
rename to brain/knowledge/decisions/000015-jit-provisioning-plans-imply-unlimited-seats.md
diff --git a/brain/decisions/000015-streaming-csv-fanout-is-a-bounded-fire-and-forget-action.md b/brain/knowledge/decisions/000015-streaming-csv-fanout-is-a-bounded-fire-and-forget-action.md
similarity index 100%
rename from brain/decisions/000015-streaming-csv-fanout-is-a-bounded-fire-and-forget-action.md
rename to brain/knowledge/decisions/000015-streaming-csv-fanout-is-a-bounded-fire-and-forget-action.md
diff --git a/brain/decisions/000016-action-run-code-cache-is-namespaced-per-platform.md b/brain/knowledge/decisions/000016-action-run-code-cache-is-namespaced-per-platform.md
similarity index 100%
rename from brain/decisions/000016-action-run-code-cache-is-namespaced-per-platform.md
rename to brain/knowledge/decisions/000016-action-run-code-cache-is-namespaced-per-platform.md
diff --git a/brain/decisions/000016-ai-sdk-7-is-a-maintenance-bump-the-agent-loop-keeps-its-own-machinery.md b/brain/knowledge/decisions/000016-ai-sdk-7-is-a-maintenance-bump-the-agent-loop-keeps-its-own-machinery.md
similarity index 100%
rename from brain/decisions/000016-ai-sdk-7-is-a-maintenance-bump-the-agent-loop-keeps-its-own-machinery.md
rename to brain/knowledge/decisions/000016-ai-sdk-7-is-a-maintenance-bump-the-agent-loop-keeps-its-own-machinery.md
diff --git a/brain/decisions/000016-managed-ai-metering-moves-to-centralized-worker-execution.md b/brain/knowledge/decisions/000016-managed-ai-metering-moves-to-centralized-worker-execution.md
similarity index 100%
rename from brain/decisions/000016-managed-ai-metering-moves-to-centralized-worker-execution.md
rename to brain/knowledge/decisions/000016-managed-ai-metering-moves-to-centralized-worker-execution.md
diff --git a/brain/decisions/000017-scheduled-downgrades-cap-seats-immediately.md b/brain/knowledge/decisions/000017-scheduled-downgrades-cap-seats-immediately.md
similarity index 100%
rename from brain/decisions/000017-scheduled-downgrades-cap-seats-immediately.md
rename to brain/knowledge/decisions/000017-scheduled-downgrades-cap-seats-immediately.md
diff --git a/brain/decisions/000018-usage-counts-report-to-posthog-only.md b/brain/knowledge/decisions/000018-usage-counts-report-to-posthog-only.md
similarity index 100%
rename from brain/decisions/000018-usage-counts-report-to-posthog-only.md
rename to brain/knowledge/decisions/000018-usage-counts-report-to-posthog-only.md
diff --git a/brain/decisions/000019-autumn-platform-plan-schema-ships-additively.md b/brain/knowledge/decisions/000019-autumn-platform-plan-schema-ships-additively.md
similarity index 100%
rename from brain/decisions/000019-autumn-platform-plan-schema-ships-additively.md
rename to brain/knowledge/decisions/000019-autumn-platform-plan-schema-ships-additively.md
diff --git a/brain/decisions/000020-credit-gating-fails-open-on-an-unknown-balance.md b/brain/knowledge/decisions/000020-credit-gating-fails-open-on-an-unknown-balance.md
similarity index 100%
rename from brain/decisions/000020-credit-gating-fails-open-on-an-unknown-balance.md
rename to brain/knowledge/decisions/000020-credit-gating-fails-open-on-an-unknown-balance.md
diff --git a/brain/decisions/000021-legacy-free-platforms-are-comped-an-appsumo-clone-from-ensureenrolled.md b/brain/knowledge/decisions/000021-legacy-free-platforms-are-comped-an-appsumo-clone-from-ensureenrolled.md
similarity index 100%
rename from brain/decisions/000021-legacy-free-platforms-are-comped-an-appsumo-clone-from-ensureenrolled.md
rename to brain/knowledge/decisions/000021-legacy-free-platforms-are-comped-an-appsumo-clone-from-ensureenrolled.md
diff --git a/brain/decisions/000023-cancellation-feedback-rides-the-cancel-call.md b/brain/knowledge/decisions/000023-cancellation-feedback-rides-the-cancel-call.md
similarity index 100%
rename from brain/decisions/000023-cancellation-feedback-rides-the-cancel-call.md
rename to brain/knowledge/decisions/000023-cancellation-feedback-rides-the-cancel-call.md
diff --git a/brain/decisions/000024-configuring-an-agent-step-tool-authorises-the-action-not-its-arguments.md b/brain/knowledge/decisions/000024-configuring-an-agent-step-tool-authorises-the-action-not-its-arguments.md
similarity index 100%
rename from brain/decisions/000024-configuring-an-agent-step-tool-authorises-the-action-not-its-arguments.md
rename to brain/knowledge/decisions/000024-configuring-an-agent-step-tool-authorises-the-action-not-its-arguments.md
diff --git a/brain/decisions/000025-connection-piece-binding-is-enforced-in-the-engine.md b/brain/knowledge/decisions/000025-connection-piece-binding-is-enforced-in-the-engine.md
similarity index 100%
rename from brain/decisions/000025-connection-piece-binding-is-enforced-in-the-engine.md
rename to brain/knowledge/decisions/000025-connection-piece-binding-is-enforced-in-the-engine.md
diff --git a/brain/decisions/000026-delete-platform-is-a-cloud-owner-action-purged-by-one-cascading-job.md b/brain/knowledge/decisions/000026-delete-platform-is-a-cloud-owner-action-purged-by-one-cascading-job.md
similarity index 100%
rename from brain/decisions/000026-delete-platform-is-a-cloud-owner-action-purged-by-one-cascading-job.md
rename to brain/knowledge/decisions/000026-delete-platform-is-a-cloud-owner-action-purged-by-one-cascading-job.md
diff --git a/brain/decisions/index.md b/brain/knowledge/decisions/index.md
similarity index 100%
rename from brain/decisions/index.md
rename to brain/knowledge/decisions/index.md
diff --git a/brain/engineering/api-endpoints.md b/brain/knowledge/engineering/api-endpoints.md
similarity index 100%
rename from brain/engineering/api-endpoints.md
rename to brain/knowledge/engineering/api-endpoints.md
diff --git a/brain/engineering/architecture-spine.md b/brain/knowledge/engineering/architecture-spine.md
similarity index 100%
rename from brain/engineering/architecture-spine.md
rename to brain/knowledge/engineering/architecture-spine.md
diff --git a/brain/engineering/ci-pr-review-hygiene.md b/brain/knowledge/engineering/ci-pr-review-hygiene.md
similarity index 100%
rename from brain/engineering/ci-pr-review-hygiene.md
rename to brain/knowledge/engineering/ci-pr-review-hygiene.md
diff --git a/brain/engineering/cloud-deployment-paths.md b/brain/knowledge/engineering/cloud-deployment-paths.md
similarity index 100%
rename from brain/engineering/cloud-deployment-paths.md
rename to brain/knowledge/engineering/cloud-deployment-paths.md
diff --git a/brain/engineering/engineering-handbook-playbooks.md b/brain/knowledge/engineering/engineering-handbook-playbooks.md
similarity index 100%
rename from brain/engineering/engineering-handbook-playbooks.md
rename to brain/knowledge/engineering/engineering-handbook-playbooks.md
diff --git a/brain/engineering/index.md b/brain/knowledge/engineering/index.md
similarity index 100%
rename from brain/engineering/index.md
rename to brain/knowledge/engineering/index.md
diff --git a/brain/engineering/server-module-anatomy.md b/brain/knowledge/engineering/server-module-anatomy.md
similarity index 100%
rename from brain/engineering/server-module-anatomy.md
rename to brain/knowledge/engineering/server-module-anatomy.md
diff --git a/brain/engineering/web-feature-anatomy.md b/brain/knowledge/engineering/web-feature-anatomy.md
similarity index 100%
rename from brain/engineering/web-feature-anatomy.md
rename to brain/knowledge/engineering/web-feature-anatomy.md
diff --git a/brain/eventing-webhooks/event-destinations.md b/brain/knowledge/eventing-webhooks/event-destinations.md
similarity index 100%
rename from brain/eventing-webhooks/event-destinations.md
rename to brain/knowledge/eventing-webhooks/event-destinations.md
diff --git a/brain/eventing-webhooks/flow-failure-alerts.md b/brain/knowledge/eventing-webhooks/flow-failure-alerts.md
similarity index 100%
rename from brain/eventing-webhooks/flow-failure-alerts.md
rename to brain/knowledge/eventing-webhooks/flow-failure-alerts.md
diff --git a/brain/eventing-webhooks/index.md b/brain/knowledge/eventing-webhooks/index.md
similarity index 100%
rename from brain/eventing-webhooks/index.md
rename to brain/knowledge/eventing-webhooks/index.md
diff --git a/brain/eventing-webhooks/pubsub-is-the-one-shared-redis-subscriber-reuse-it.md b/brain/knowledge/eventing-webhooks/pubsub-is-the-one-shared-redis-subscriber-reuse-it.md
similarity index 100%
rename from brain/eventing-webhooks/pubsub-is-the-one-shared-redis-subscriber-reuse-it.md
rename to brain/knowledge/eventing-webhooks/pubsub-is-the-one-shared-redis-subscriber-reuse-it.md
diff --git a/brain/eventing-webhooks/webhooks.md b/brain/knowledge/eventing-webhooks/webhooks.md
similarity index 100%
rename from brain/eventing-webhooks/webhooks.md
rename to brain/knowledge/eventing-webhooks/webhooks.md
diff --git a/brain/execution-runtime/benchmark-cli.md b/brain/knowledge/execution-runtime/benchmark-cli.md
similarity index 100%
rename from brain/execution-runtime/benchmark-cli.md
rename to brain/knowledge/execution-runtime/benchmark-cli.md
diff --git a/brain/execution-runtime/gotcha-code-cache-is-namespaced-by-flowversionid-never-reuse-a-constant.md b/brain/knowledge/execution-runtime/gotcha-code-cache-is-namespaced-by-flowversionid-never-reuse-a-constant.md
similarity index 100%
rename from brain/execution-runtime/gotcha-code-cache-is-namespaced-by-flowversionid-never-reuse-a-constant.md
rename to brain/knowledge/execution-runtime/gotcha-code-cache-is-namespaced-by-flowversionid-never-reuse-a-constant.md
diff --git a/brain/execution-runtime/index.md b/brain/knowledge/execution-runtime/index.md
similarity index 100%
rename from brain/execution-runtime/index.md
rename to brain/knowledge/execution-runtime/index.md
diff --git a/brain/execution-runtime/workers.md b/brain/knowledge/execution-runtime/workers.md
similarity index 100%
rename from brain/execution-runtime/workers.md
rename to brain/knowledge/execution-runtime/workers.md
diff --git a/brain/flows-execution/action-run.md b/brain/knowledge/flows-execution/action-run.md
similarity index 100%
rename from brain/flows-execution/action-run.md
rename to brain/knowledge/flows-execution/action-run.md
diff --git a/brain/flows-execution/chat.md b/brain/knowledge/flows-execution/chat.md
similarity index 100%
rename from brain/flows-execution/chat.md
rename to brain/knowledge/flows-execution/chat.md
diff --git a/brain/flows-execution/flow-runs.md b/brain/knowledge/flows-execution/flow-runs.md
similarity index 100%
rename from brain/flows-execution/flow-runs.md
rename to brain/knowledge/flows-execution/flow-runs.md
diff --git a/brain/flows-execution/flows.md b/brain/knowledge/flows-execution/flows.md
similarity index 100%
rename from brain/flows-execution/flows.md
rename to brain/knowledge/flows-execution/flows.md
diff --git a/brain/flows-execution/folders.md b/brain/knowledge/flows-execution/folders.md
similarity index 100%
rename from brain/flows-execution/folders.md
rename to brain/knowledge/flows-execution/folders.md
diff --git a/brain/flows-execution/formulas.md b/brain/knowledge/flows-execution/formulas.md
similarity index 100%
rename from brain/flows-execution/formulas.md
rename to brain/knowledge/flows-execution/formulas.md
diff --git a/brain/flows-execution/gotcha-a-chat-tool-lives-in-four-files-and-losing-the-worker-one-fails-silently.md b/brain/knowledge/flows-execution/gotcha-a-chat-tool-lives-in-four-files-and-losing-the-worker-one-fails-silently.md
similarity index 100%
rename from brain/flows-execution/gotcha-a-chat-tool-lives-in-four-files-and-losing-the-worker-one-fails-silently.md
rename to brain/knowledge/flows-execution/gotcha-a-chat-tool-lives-in-four-files-and-losing-the-worker-one-fails-silently.md
diff --git a/brain/flows-execution/human-input.md b/brain/knowledge/flows-execution/human-input.md
similarity index 100%
rename from brain/flows-execution/human-input.md
rename to brain/knowledge/flows-execution/human-input.md
diff --git a/brain/flows-execution/index.md b/brain/knowledge/flows-execution/index.md
similarity index 100%
rename from brain/flows-execution/index.md
rename to brain/knowledge/flows-execution/index.md
diff --git a/brain/flows-execution/subflows.md b/brain/knowledge/flows-execution/subflows.md
similarity index 100%
rename from brain/flows-execution/subflows.md
rename to brain/knowledge/flows-execution/subflows.md
diff --git a/brain/flows-execution/templates.md b/brain/knowledge/flows-execution/templates.md
similarity index 100%
rename from brain/flows-execution/templates.md
rename to brain/knowledge/flows-execution/templates.md
diff --git a/brain/flows-execution/triggers.md b/brain/knowledge/flows-execution/triggers.md
similarity index 100%
rename from brain/flows-execution/triggers.md
rename to brain/knowledge/flows-execution/triggers.md
diff --git a/brain/flows-execution/variables.md b/brain/knowledge/flows-execution/variables.md
similarity index 100%
rename from brain/flows-execution/variables.md
rename to brain/knowledge/flows-execution/variables.md
diff --git a/brain/knowledge/index.md b/brain/knowledge/index.md
new file mode 100644
index 000000000000..55eb9a5547a8
--- /dev/null
+++ b/brain/knowledge/index.md
@@ -0,0 +1,30 @@
+---
+icon: 🧠
+---
+
+# Brain
+
+Durable context for this repo. Every folder here is a page in Craftspace, and every page here is a file in
+the repo, so the team reads the same thing whether they open GitHub or the app.
+
+This page is a **spine**: one line per Area, pointing at the page that holds it. Hard-to-reverse calls live
+as Decisions, not here.
+
+## Areas
+
+Add one folder per Area that fits what this project actually holds — an engineering project grows different
+ones than a sales project does. `decisions/` is the only one every repo starts with. Replace these examples
+with your own and keep the shape: **bold name**, then the one line that says what a reader will find there.
+
+- **Example Area** — what this Area covers, and the one gotcha that bites people in it
+
+## How a page is shaped
+
+One Area owns exactly one page, and that page is a glossary spine: one line per term, defining what the
+term IS. A term that outgrows its line graduates to its own file beside the page. Search before you write —
+a second page for an Area that already has one is the failure this structure exists to prevent.
+
+## Gotchas
+
+- Craftspace mirrors this folder read-only. Edit the files here and merge, and the pages follow.
+- `<area>/index.md` is the page for `<area>`; a file beside it is that page's child.
diff --git a/brain/pieces-engine/building-pieces.md b/brain/knowledge/pieces-engine/building-pieces.md
similarity index 100%
rename from brain/pieces-engine/building-pieces.md
rename to brain/knowledge/pieces-engine/building-pieces.md
diff --git a/brain/pieces-engine/index.md b/brain/knowledge/pieces-engine/index.md
similarity index 100%
rename from brain/pieces-engine/index.md
rename to brain/knowledge/pieces-engine/index.md
diff --git a/brain/pieces-engine/piece-sets.md b/brain/knowledge/pieces-engine/piece-sets.md
similarity index 100%
rename from brain/pieces-engine/piece-sets.md
rename to brain/knowledge/pieces-engine/piece-sets.md
diff --git a/brain/pieces-engine/pieces.md b/brain/knowledge/pieces-engine/pieces.md
similarity index 100%
rename from brain/pieces-engine/pieces.md
rename to brain/knowledge/pieces-engine/pieces.md
diff --git a/brain/platform-editions-ee/ee-overview.md b/brain/knowledge/platform-editions-ee/ee-overview.md
similarity index 100%
rename from brain/platform-editions-ee/ee-overview.md
rename to brain/knowledge/platform-editions-ee/ee-overview.md
diff --git a/brain/platform-editions-ee/ee-platform-plans-billing.md b/brain/knowledge/platform-editions-ee/ee-platform-plans-billing.md
similarity index 100%
rename from brain/platform-editions-ee/ee-platform-plans-billing.md
rename to brain/knowledge/platform-editions-ee/ee-platform-plans-billing.md
diff --git a/brain/platform-editions-ee/ee-projects-rbac.md b/brain/knowledge/platform-editions-ee/ee-projects-rbac.md
similarity index 100%
rename from brain/platform-editions-ee/ee-projects-rbac.md
rename to brain/knowledge/platform-editions-ee/ee-projects-rbac.md
diff --git a/brain/platform-editions-ee/embed.md b/brain/knowledge/platform-editions-ee/embed.md
similarity index 100%
rename from brain/platform-editions-ee/embed.md
rename to brain/knowledge/platform-editions-ee/embed.md
diff --git a/brain/platform-editions-ee/index.md b/brain/knowledge/platform-editions-ee/index.md
similarity index 100%
rename from brain/platform-editions-ee/index.md
rename to brain/knowledge/platform-editions-ee/index.md
diff --git a/brain/platform-editions-ee/license-keys.md b/brain/knowledge/platform-editions-ee/license-keys.md
similarity index 100%
rename from brain/platform-editions-ee/license-keys.md
rename to brain/knowledge/platform-editions-ee/license-keys.md
diff --git a/brain/platform-editions-ee/platform-configuration.md b/brain/knowledge/platform-editions-ee/platform-configuration.md
similarity index 100%
rename from brain/platform-editions-ee/platform-configuration.md
rename to brain/knowledge/platform-editions-ee/platform-configuration.md
diff --git a/brain/platform-editions-ee/platform-copilot.md b/brain/knowledge/platform-editions-ee/platform-copilot.md
similarity index 100%
rename from brain/platform-editions-ee/platform-copilot.md
rename to brain/knowledge/platform-editions-ee/platform-copilot.md
diff --git a/brain/platform-editions-ee/projects.md b/brain/knowledge/platform-editions-ee/projects.md
similarity index 100%
rename from brain/platform-editions-ee/projects.md
rename to brain/knowledge/platform-editions-ee/projects.md
diff --git a/brain/platform-editions-ee/user-invitations.md b/brain/knowledge/platform-editions-ee/user-invitations.md
similarity index 100%
rename from brain/platform-editions-ee/user-invitations.md
rename to brain/knowledge/platform-editions-ee/user-invitations.md
diff --git a/brain/platform-editions-ee/users.md b/brain/knowledge/platform-editions-ee/users.md
similarity index 100%
rename from brain/platform-editions-ee/users.md
rename to brain/knowledge/platform-editions-ee/users.md
diff --git a/brain/playbooks/AGENTS.md b/brain/playbooks/AGENTS.md
new file mode 100644
index 000000000000..2e291a12e641
--- /dev/null
+++ b/brain/playbooks/AGENTS.md
@@ -0,0 +1,27 @@
+<!-- craftspace:playbook-guide v1 -->
+
+# Craftspace Playbooks
+
+`brain/playbooks/` holds the team Playbooks that Craftspace loads for Cubie. `AGENTS.md` and
+`CLAUDE.md` are the authoring guides for this directory. They are not Playbook packages.
+
+Every other direct child must be a Playbook package directory:
+
+~~~text
+customer-research/
+  playbook.json
+  skills/
+    interview-customers/
+      SKILL.md
+      attachments/
+~~~
+
+Use a Playbook when the team needs the same focused instructions, references, or starter files more than
+once. `playbook.json` has `name`, `displayName`, and `description`. The package folder and manifest name
+must match. Each Skill folder and its frontmatter `name` must match too.
+
+For a repo-managed Playbook, change `brain/playbooks/<name>/` in a local checkout and open a pull
+request. Craftspace reads it after merge and never writes it back. Do not call `upsert_playbook` for a
+repo-managed Playbook.
+
+<!-- /craftspace:playbook-guide -->
diff --git a/brain/playbooks/CLAUDE.md b/brain/playbooks/CLAUDE.md
new file mode 100644
index 000000000000..2e291a12e641
--- /dev/null
+++ b/brain/playbooks/CLAUDE.md
@@ -0,0 +1,27 @@
+<!-- craftspace:playbook-guide v1 -->
+
+# Craftspace Playbooks
+
+`brain/playbooks/` holds the team Playbooks that Craftspace loads for Cubie. `AGENTS.md` and
+`CLAUDE.md` are the authoring guides for this directory. They are not Playbook packages.
+
+Every other direct child must be a Playbook package directory:
+
+~~~text
+customer-research/
+  playbook.json
+  skills/
+    interview-customers/
+      SKILL.md
+      attachments/
+~~~
+
+Use a Playbook when the team needs the same focused instructions, references, or starter files more than
+once. `playbook.json` has `name`, `displayName`, and `description`. The package folder and manifest name
+must match. Each Skill folder and its frontmatter `name` must match too.
+
+For a repo-managed Playbook, change `brain/playbooks/<name>/` in a local checkout and open a pull
+request. Craftspace reads it after merge and never writes it back. Do not call `upsert_playbook` for a
+repo-managed Playbook.
+
+<!-- /craftspace:playbook-guide -->