journey-substrate

Name: journey-substrate
Author: butterbase-ai

533stars40forks

How to install journey-substrate?

butterbase-ai/butterbase-skills/journey-substrate

$npx -y skills add butterbase-ai/butterbase-skills --skill journey-substrate

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Journey Substrate Stage (optional)
2
3	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.
4
5	## When to use
6
7	Invoke automatically when the journey orchestrator's cursor reaches `substrate`. The row is optional in the checklist; skip silently if the user declines.
8
9	## Procedure
10
11	0. 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`.
12
13	1. Confirm. Ask the user:
14	> "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)"
15
16	Default: skip.
17
18	2. 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.
19
20	3. On yes:
21	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`).
22	b. Link the app. Use whichever surface you have:
23	- MCP: `manage_app` with `{ action: "link_substrate", app_id: "<app_id>" }`.
24	- CLI: `butterbase apps link-substrate <app_id>`.
25	- 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.
26	c. Verify: `manage_app` with `{ action: "get_config", app_id: "<app_id>" }` and assert `substrate_user_id` is non-null.
27	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.
28
29	4. Write artifact. `docs/butterbase/04b-substrate.md`:
30
31	```markdown
32	---
33	linked_at: <ISO>
34	app_id: <id>
35	substrate_user_id: <id>
36	---
37
38	# Substrate Linkage
39
40	- App linked at <ISO>
41	- Substrate user ID: <id>
42	- Smoke: <pass / skipped — no function yet>
43	```
44
45	5. Update state. Tick the `substrate` row in `00-state.md`.
46
47	## Anti-patterns
48
49	- ❌ Auto-linking without asking. Substrate is a privacy-sensitive surface.
50	- ❌ Linking before the app has any function deployed. Wait until `journey-functions` has run.
51	- ❌ Forgetting to handle the "substrate not yet provisioned" case. Lazy provisioning is by design.

People who liked this also viewed

6 picks

Type

journey-substrate

533stars40forks

View on GitHub

How to install journey-substrate?

butterbase-ai/butterbase-skills/journey-substrate

$npx -y skills add butterbase-ai/butterbase-skills --skill journey-substrate

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Journey Substrate Stage (optional)
2
3	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.
4
5	## When to use
6
7	Invoke automatically when the journey orchestrator's cursor reaches `substrate`. The row is optional in the checklist; skip silently if the user declines.
8
9	## Procedure
10
11	0. 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`.
12
13	1. Confirm. Ask the user:
14	> "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)"
15
16	Default: skip.
17
18	2. 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.
19
20	3. On yes:
21	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`).
22	b. Link the app. Use whichever surface you have:
23	- MCP: `manage_app` with `{ action: "link_substrate", app_id: "<app_id>" }`.
24	- CLI: `butterbase apps link-substrate <app_id>`.
25	- 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.
26	c. Verify: `manage_app` with `{ action: "get_config", app_id: "<app_id>" }` and assert `substrate_user_id` is non-null.
27	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.
28
29	4. Write artifact. `docs/butterbase/04b-substrate.md`:
30
31	```markdown
32	---
33	linked_at: <ISO>
34	app_id: <id>
35	substrate_user_id: <id>
36	---
37
38	# Substrate Linkage
39
40	- App linked at <ISO>
41	- Substrate user ID: <id>
42	- Smoke: <pass / skipped — no function yet>
43	```
44
45	5. Update state. Tick the `substrate` row in `00-state.md`.
46
47	## Anti-patterns
48
49	- ❌ Auto-linking without asking. Substrate is a privacy-sensitive surface.
50	- ❌ Linking before the app has any function deployed. Wait until `journey-functions` has run.
51	- ❌ Forgetting to handle the "substrate not yet provisioned" case. Lazy provisioning is by design.

People who liked this also viewed

6 picks

Type