From ada6b3aa60addc5309b4b1ce35edc2981ffffc16 Mon Sep 17 00:00:00 2001 From: "craftspace-bot[bot]" <308386655+craftspace-bot[bot]@users.noreply.github.com> Date: Sat, 15 Aug 2026 12:55:40 +0300 Subject: [PATCH] docs(brain): move the page tree into brain/knowledge and update the Craftspace guide (#14829) Co-authored-by: craftspace-bot[bot] <308386655+craftspace-bot[bot]@users.noreply.github.com> --- AGENTS.md | 102 +++++++ CLAUDE.md | 266 +++++++++++++++++- .../ai-intelligence/ai-agents.md | 0 .../{ => knowledge}/ai-intelligence/ai-mcp.md | 0 .../ai-intelligence/ai-providers.md | 0 .../{ => knowledge}/ai-intelligence/index.md | 0 .../ai-intelligence/mcp-server.md | 0 brain/{ => knowledge}/ask-tool-check.md | 0 .../connections-auth/api-keys.md | 0 .../connections-auth/app-connections.md | 0 .../connections-auth/ce-authentication.md | 0 .../ee-authentication-sso-rbac.md | 0 .../connections-auth/global-connections.md | 0 .../{ => knowledge}/connections-auth/index.md | 0 .../connections-auth/managed-auth.md | 0 .../connections-auth/oauth-apps.md | 0 .../{ => knowledge}/connections-auth/scim.md | 0 .../connections-auth/secret-managers.md | 0 .../data-storage-observability/analytics.md | 0 .../data-storage-observability/audit-logs.md | 0 .../file-storage.md | 0 .../data-storage-observability/index.md | 0 .../key-value-store.md | 0 .../knowledge-base.md | 0 .../data-storage-observability/tables.md | 0 ...ox-one-job-per-worker-scale-by-replicas.md | 0 ...concurrency-honor-ap-worker-concurrency.md | 0 ...-run-time-callbacks-directly-to-the-app.md | 0 ...ce-versions-in-the-flow-bundle-manifest.md | 0 ...re-distributed-as-links-resolved-lazily.md | 0 ...-set-visibility-is-derived-at-read-time.md | 0 ...file-writes-go-through-the-app-one-path.md | 0 ...-post-confirmation-on-a-dedicated-route.md | 0 ...k-is-redis-durable-not-postgres-durable.md | 0 ...-by-dropping-global-multipart-buffering.md | 0 ...at-floor-is-enforced-db-authoritatively.md | 0 ...-pure-execute-cloud-run-pool-superseded.md | 0 ...ch-as-synchronous-user-interaction-jobs.md | 0 ...00014-pending-invitations-reserve-seats.md | 0 ...nputs-resolve-to-a-lazy-apstreamingfile.md | 0 ...rovisioning-plans-imply-unlimited-seats.md | 0 ...out-is-a-bounded-fire-and-forget-action.md | 0 ...n-code-cache-is-namespaced-per-platform.md | 0 ...-the-agent-loop-keeps-its-own-machinery.md | 0 ...g-moves-to-centralized-worker-execution.md | 0 ...eduled-downgrades-cap-seats-immediately.md | 0 ...018-usage-counts-report-to-posthog-only.md | 0 ...n-platform-plan-schema-ships-additively.md | 0 ...gating-fails-open-on-an-unknown-balance.md | 0 ...ed-an-appsumo-clone-from-ensureenrolled.md | 0 ...ellation-feedback-rides-the-cancel-call.md | 0 ...authorises-the-action-not-its-arguments.md | 0 ...piece-binding-is-enforced-in-the-engine.md | 0 ...wner-action-purged-by-one-cascading-job.md | 0 brain/{ => knowledge}/decisions/index.md | 0 .../engineering/api-endpoints.md | 0 .../engineering/architecture-spine.md | 0 .../engineering/ci-pr-review-hygiene.md | 0 .../engineering/cloud-deployment-paths.md | 0 .../engineering-handbook-playbooks.md | 0 brain/{ => knowledge}/engineering/index.md | 0 .../engineering/server-module-anatomy.md | 0 .../engineering/web-feature-anatomy.md | 0 .../eventing-webhooks/event-destinations.md | 0 .../eventing-webhooks/flow-failure-alerts.md | 0 .../eventing-webhooks/index.md | 0 ...he-one-shared-redis-subscriber-reuse-it.md | 0 .../eventing-webhooks/webhooks.md | 0 .../execution-runtime/benchmark-cli.md | 0 ...by-flowversionid-never-reuse-a-constant.md | 0 .../execution-runtime/index.md | 0 .../execution-runtime/workers.md | 0 .../flows-execution/action-run.md | 0 brain/{ => knowledge}/flows-execution/chat.md | 0 .../flows-execution/flow-runs.md | 0 .../{ => knowledge}/flows-execution/flows.md | 0 .../flows-execution/folders.md | 0 .../flows-execution/formulas.md | 0 ...nd-losing-the-worker-one-fails-silently.md | 0 .../flows-execution/human-input.md | 0 .../{ => knowledge}/flows-execution/index.md | 0 .../flows-execution/subflows.md | 0 .../flows-execution/templates.md | 0 .../flows-execution/triggers.md | 0 .../flows-execution/variables.md | 0 brain/knowledge/index.md | 30 ++ .../pieces-engine/building-pieces.md | 0 brain/{ => knowledge}/pieces-engine/index.md | 0 .../pieces-engine/piece-sets.md | 0 brain/{ => knowledge}/pieces-engine/pieces.md | 0 .../platform-editions-ee/ee-overview.md | 0 .../ee-platform-plans-billing.md | 0 .../platform-editions-ee/ee-projects-rbac.md | 0 .../platform-editions-ee/embed.md | 0 .../platform-editions-ee/index.md | 0 .../platform-editions-ee/license-keys.md | 0 .../platform-configuration.md | 0 .../platform-editions-ee/platform-copilot.md | 0 .../platform-editions-ee/projects.md | 0 .../platform-editions-ee/user-invitations.md | 0 .../platform-editions-ee/users.md | 0 brain/playbooks/AGENTS.md | 27 ++ brain/playbooks/CLAUDE.md | 27 ++ 103 files changed, 451 insertions(+), 1 deletion(-) mode change 120000 => 100644 CLAUDE.md rename brain/{ => knowledge}/ai-intelligence/ai-agents.md (100%) rename brain/{ => knowledge}/ai-intelligence/ai-mcp.md (100%) rename brain/{ => knowledge}/ai-intelligence/ai-providers.md (100%) rename brain/{ => knowledge}/ai-intelligence/index.md (100%) rename brain/{ => knowledge}/ai-intelligence/mcp-server.md (100%) rename brain/{ => knowledge}/ask-tool-check.md (100%) rename brain/{ => knowledge}/connections-auth/api-keys.md (100%) rename brain/{ => knowledge}/connections-auth/app-connections.md (100%) rename brain/{ => knowledge}/connections-auth/ce-authentication.md (100%) rename brain/{ => knowledge}/connections-auth/ee-authentication-sso-rbac.md (100%) rename brain/{ => knowledge}/connections-auth/global-connections.md (100%) rename brain/{ => knowledge}/connections-auth/index.md (100%) rename brain/{ => knowledge}/connections-auth/managed-auth.md (100%) rename brain/{ => knowledge}/connections-auth/oauth-apps.md (100%) rename brain/{ => knowledge}/connections-auth/scim.md (100%) rename brain/{ => knowledge}/connections-auth/secret-managers.md (100%) rename brain/{ => knowledge}/data-storage-observability/analytics.md (100%) rename brain/{ => knowledge}/data-storage-observability/audit-logs.md (100%) rename brain/{ => knowledge}/data-storage-observability/file-storage.md (100%) rename brain/{ => knowledge}/data-storage-observability/index.md (100%) rename brain/{ => knowledge}/data-storage-observability/key-value-store.md (100%) rename brain/{ => knowledge}/data-storage-observability/knowledge-base.md (100%) rename brain/{ => knowledge}/data-storage-observability/tables.md (100%) rename brain/{ => knowledge}/decisions/000001-worker-is-the-sandbox-one-job-per-worker-scale-by-replicas.md (100%) rename brain/{ => knowledge}/decisions/000002-transitional-multi-box-concurrency-honor-ap-worker-concurrency.md (100%) rename brain/{ => knowledge}/decisions/000003-engine-posts-run-time-callbacks-directly-to-the-app.md (100%) rename brain/{ => knowledge}/decisions/000005-freeze-piece-versions-in-the-flow-bundle-manifest.md (100%) rename brain/{ => knowledge}/decisions/000006-pieces-are-distributed-as-links-resolved-lazily.md (100%) rename brain/{ => knowledge}/decisions/000007-piece-set-visibility-is-derived-at-read-time.md (100%) rename brain/{ => knowledge}/decisions/000008-streaming-file-writes-go-through-the-app-one-path.md (100%) rename brain/{ => knowledge}/decisions/000009-approval-links-require-a-post-confirmation-on-a-dedicated-route.md (100%) rename brain/{ => knowledge}/decisions/000010-async-webhook-ack-is-redis-durable-not-postgres-durable.md (100%) rename brain/{ => knowledge}/decisions/000011-webhook-files-stream-to-s3-by-dropping-global-multipart-buffering.md (100%) rename brain/{ => knowledge}/decisions/000013-active-user-seat-floor-is-enforced-db-authoritatively.md (100%) rename brain/{ => knowledge}/decisions/000013-sandbox-pool-is-a-pure-execute-cloud-run-pool-superseded.md (100%) rename brain/{ => knowledge}/decisions/000014-action-runs-dispatch-as-synchronous-user-interaction-jobs.md (100%) rename brain/{ => knowledge}/decisions/000014-pending-invitations-reserve-seats.md (100%) rename brain/{ => knowledge}/decisions/000014-streaming-file-inputs-resolve-to-a-lazy-apstreamingfile.md (100%) rename brain/{ => knowledge}/decisions/000015-jit-provisioning-plans-imply-unlimited-seats.md (100%) rename brain/{ => knowledge}/decisions/000015-streaming-csv-fanout-is-a-bounded-fire-and-forget-action.md (100%) rename brain/{ => knowledge}/decisions/000016-action-run-code-cache-is-namespaced-per-platform.md (100%) rename brain/{ => knowledge}/decisions/000016-ai-sdk-7-is-a-maintenance-bump-the-agent-loop-keeps-its-own-machinery.md (100%) rename brain/{ => knowledge}/decisions/000016-managed-ai-metering-moves-to-centralized-worker-execution.md (100%) rename brain/{ => knowledge}/decisions/000017-scheduled-downgrades-cap-seats-immediately.md (100%) rename brain/{ => knowledge}/decisions/000018-usage-counts-report-to-posthog-only.md (100%) rename brain/{ => knowledge}/decisions/000019-autumn-platform-plan-schema-ships-additively.md (100%) rename brain/{ => knowledge}/decisions/000020-credit-gating-fails-open-on-an-unknown-balance.md (100%) rename brain/{ => knowledge}/decisions/000021-legacy-free-platforms-are-comped-an-appsumo-clone-from-ensureenrolled.md (100%) rename brain/{ => knowledge}/decisions/000023-cancellation-feedback-rides-the-cancel-call.md (100%) rename brain/{ => knowledge}/decisions/000024-configuring-an-agent-step-tool-authorises-the-action-not-its-arguments.md (100%) rename brain/{ => knowledge}/decisions/000025-connection-piece-binding-is-enforced-in-the-engine.md (100%) rename brain/{ => knowledge}/decisions/000026-delete-platform-is-a-cloud-owner-action-purged-by-one-cascading-job.md (100%) rename brain/{ => knowledge}/decisions/index.md (100%) rename brain/{ => knowledge}/engineering/api-endpoints.md (100%) rename brain/{ => knowledge}/engineering/architecture-spine.md (100%) rename brain/{ => knowledge}/engineering/ci-pr-review-hygiene.md (100%) rename brain/{ => knowledge}/engineering/cloud-deployment-paths.md (100%) rename brain/{ => knowledge}/engineering/engineering-handbook-playbooks.md (100%) rename brain/{ => knowledge}/engineering/index.md (100%) rename brain/{ => knowledge}/engineering/server-module-anatomy.md (100%) rename brain/{ => knowledge}/engineering/web-feature-anatomy.md (100%) rename brain/{ => knowledge}/eventing-webhooks/event-destinations.md (100%) rename brain/{ => knowledge}/eventing-webhooks/flow-failure-alerts.md (100%) rename brain/{ => knowledge}/eventing-webhooks/index.md (100%) rename brain/{ => knowledge}/eventing-webhooks/pubsub-is-the-one-shared-redis-subscriber-reuse-it.md (100%) rename brain/{ => knowledge}/eventing-webhooks/webhooks.md (100%) rename brain/{ => knowledge}/execution-runtime/benchmark-cli.md (100%) rename brain/{ => knowledge}/execution-runtime/gotcha-code-cache-is-namespaced-by-flowversionid-never-reuse-a-constant.md (100%) rename brain/{ => knowledge}/execution-runtime/index.md (100%) rename brain/{ => knowledge}/execution-runtime/workers.md (100%) rename brain/{ => knowledge}/flows-execution/action-run.md (100%) rename brain/{ => knowledge}/flows-execution/chat.md (100%) rename brain/{ => knowledge}/flows-execution/flow-runs.md (100%) rename brain/{ => knowledge}/flows-execution/flows.md (100%) rename brain/{ => knowledge}/flows-execution/folders.md (100%) rename brain/{ => knowledge}/flows-execution/formulas.md (100%) rename brain/{ => knowledge}/flows-execution/gotcha-a-chat-tool-lives-in-four-files-and-losing-the-worker-one-fails-silently.md (100%) rename brain/{ => knowledge}/flows-execution/human-input.md (100%) rename brain/{ => knowledge}/flows-execution/index.md (100%) rename brain/{ => knowledge}/flows-execution/subflows.md (100%) rename brain/{ => knowledge}/flows-execution/templates.md (100%) rename brain/{ => knowledge}/flows-execution/triggers.md (100%) rename brain/{ => knowledge}/flows-execution/variables.md (100%) create mode 100644 brain/knowledge/index.md rename brain/{ => knowledge}/pieces-engine/building-pieces.md (100%) rename brain/{ => knowledge}/pieces-engine/index.md (100%) rename brain/{ => knowledge}/pieces-engine/piece-sets.md (100%) rename brain/{ => knowledge}/pieces-engine/pieces.md (100%) rename brain/{ => knowledge}/platform-editions-ee/ee-overview.md (100%) rename brain/{ => knowledge}/platform-editions-ee/ee-platform-plans-billing.md (100%) rename brain/{ => knowledge}/platform-editions-ee/ee-projects-rbac.md (100%) rename brain/{ => knowledge}/platform-editions-ee/embed.md (100%) rename brain/{ => knowledge}/platform-editions-ee/index.md (100%) rename brain/{ => knowledge}/platform-editions-ee/license-keys.md (100%) rename brain/{ => knowledge}/platform-editions-ee/platform-configuration.md (100%) rename brain/{ => knowledge}/platform-editions-ee/platform-copilot.md (100%) rename brain/{ => knowledge}/platform-editions-ee/projects.md (100%) rename brain/{ => knowledge}/platform-editions-ee/user-invitations.md (100%) rename brain/{ => knowledge}/platform-editions-ee/users.md (100%) create mode 100644 brain/playbooks/AGENTS.md create mode 100644 brain/playbooks/CLAUDE.md 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 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//index.md` is the page for + ``, 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/.md` | +| A repeatable procedure | `brain/knowledge//.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/.md` | +| A dated one-off with nothing to teach | one line in `brain/knowledge/memory.md` | + +`` 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 ` 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. + + 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//` (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//index.md` | 9 areas | First stop for an unfamiliar subsystem | Area glossary + list of its pages | +| `brain//*.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`, `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= # 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.` 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) + + +## 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 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//index.md` is the page for + ``, 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/.md` | +| A repeatable procedure | `brain/knowledge//.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/.md` | +| A dated one-off with nothing to teach | one line in `brain/knowledge/memory.md` | + +`` 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 ` 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. + + 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. +- `/index.md` is the page for ``; 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 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//` 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. + + 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 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//` 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. + +