| name | journey-substrate |
| description | Use as the optional substrate-linking stage of the Butterbase journey, after deploy and before submit. Asks whether to connect the deployed app to the owner's substrate (so functions get ctx.substrate). Skipped by default in hackathon mode. |
Journey Substrate Stage (optional)
Connect the deployed app to the owner's substrate so functions get ctx.substrate injected at cold start. Skip if the user has no AI-agent / memory use case.
When to use
Invoke automatically when the journey orchestrator's cursor reaches substrate. The row is optional in the checklist; skip silently if the user declines.
Procedure
-
Refresh docs. Call butterbase_docs with topic: "substrate". If the plan mentions AI memory / agent state / cross-session knowledge, also WebFetch https://docs.butterbase.ai/substrate. Skip if docs/butterbase/03b-docs-cache.md already covers substrate.
-
Confirm. Ask the user:
"Connect <app_id> to your substrate? This lets the app's functions read/write your agent memory via ctx.substrate. You can disable later. (yes / skip)"
Default: skip.
-
On skip: mark the row - [x] substrate (skipped — no agent memory needed) in docs/butterbase/00-state.md. Write docs/butterbase/04b-substrate.md with one line: Skipped on <date>. Return.
-
On yes:
a. If platform_users.substrate_provisioned_at is NULL for the caller, call POST /v1/me/substrate/provision first (or invoke whatever MCP wrapper exists — check butterbase_docs topic substrate).
b. Link the app. Use whichever surface you have:
- MCP:
manage_app with { action: "link_substrate", app_id: "<app_id>" }.
- CLI:
butterbase apps link-substrate <app_id>.
- REST (curl):
POST /v1/me/apps/<app_id>/substrate-link with empty body and Authorization: Bearer <bb_sk_*> for the app owner. The route enforces caller == app owner and sets apps.substrate_user_id to the caller's id.
c. Verify: manage_app with { action: "get_config", app_id: "<app_id>" } and assert substrate_user_id is non-null.
d. Smoke: invoke any HTTP function the app already has and check ctx.substrate is defined (if the function logs it). If no function exists yet, skip the smoke and note in the artifact.
-
Write artifact. docs/butterbase/04b-substrate.md:
---
linked_at: <ISO>
app_id: <id>
substrate_user_id: <id>
---
# Substrate Linkage
- App linked at <ISO>
- Substrate user ID: <id>
- Smoke: <pass / skipped — no function yet>
-
Update state. Tick the substrate row in 00-state.md.
Anti-patterns
- ❌ Auto-linking without asking. Substrate is a privacy-sensitive surface.
- ❌ Linking before the app has any function deployed. Wait until
journey-functions has run.
- ❌ Forgetting to handle the "substrate not yet provisioned" case. Lazy provisioning is by design.
