Workspace types

This file is the schema of your workspace: it defines the folder "types" your AI follows when it creates and organizes things here. It is yours: edit the templates, add your own types, remove what you don't use. How the type machinery works is documented in /_docs/typed-folders.md.

How to read this file

The rules, for humans and AI alike:

• Every ## <Name> (folder) heading below is a type in active use: the AI may create folders of that shape, and the dashboard lists it.
• Only active types live in this file, and this file is the complete list: a type that is not here does not exist in this workspace. A new workspace starts with the three core types: Task (what you're working on), Integration (what your agent can use) and Note (what your agent should remember). More ready-made types (Report, Contact, Workflow) can be switched on in the dashboard's Settings page, which adds their section here; switching one off removes the section.
• These types are the whole vocabulary: something that fits none of them goes in a Note (or the closest active type), not a newly invented shape. Add a new type only when the user explicitly asks for one.
• Every type section has the same shape: a one-line purpose right under the heading (shown on its dashboard card), when to use it and when not, the folder structure with a template, and rendering notes.
• A folder becomes an instance of a type only when its main .md carries type: <Name> frontmatter. Follow the template exactly; extra frontmatter fields are fine.

Workspace settings: auto_archive_after: 30d (a folder untouched that long is shown as dormant).

Task (folder)

One unit of work with a clear done-state, tracked step by step across sessions.

Use it for: anything with an end: a feature to ship, a bug to fix, an errand with multiple steps you want the AI to pick up where it left off. Not for: reference knowledge (that's a Note) or output produced on a schedule (that's a Report).

A Task folder has a task.md and a progress/ folder:

task.md:
---
type: Task
title: <short title>
status: todo | doing | done
---
## Description
What this task is and why.

## Goal
The done state in one sentence.

## Steps
- [x] A finished step
- [ ] A pending step

Add a progress/NN-slug.md file (frontmatter title: + body) after each step you complete. The renderer lists them as a clickable progress log.

Rendering

The dashboard renders a Task with /_components/task.jsx if it exists. That file is a React function named Component taking { data }, where:

• data.title, data.status: the frontmatter fields above
• data.body: the markdown after the frontmatter
• data.path: the folder's absolute path (e.g. /tasks/sample-task)
• data.files: the folder subtree as { "relative/path": "content" } Style with Tailwind classes. With no component, the folder shows the default file cards. A global <Markdown>{markdownText}</Markdown> component (and mdToHtml(text) helper) is available to render markdown — headings, bold/italic, lists, links, code, blockquotes — so you never hand-roll it. Avoid a literal </script> inside the component source (it breaks the in-iframe render).

Integration (folder)

A third-party service the AI can operate: what it is, its Python dependencies, and the secret NAMES it needs.

Use it for: every external service you want scripts against (Stripe, Supabase, GitHub, your own API). One folder per service. Not for: background info about a service with no scripts or secrets; that's a Note.

An Integration folder has an info.md and a module.yaml:

info.md:
---
type: Integration
title: <service name>
---
What it is, and how to ask the AI to use it.

module.yaml:
dependencies:
  - <pip package>
secrets:
  - <SECRET_NAME>

Scripts stored in this folder inherit module.yaml's dependencies automatically, and its secret names feed the registry (see /_docs/secrets.md).

Rendering

Rendered by /_components/integration.jsx: shows the description, the secret NAMES it needs, and its Python dependencies. Set secret VALUES in the Secrets tab (they stay on your machine).

Note (folder)

Anything your AI should remember: decisions, how-tos, background knowledge it can look up later.

Use it for: anything you find yourself re-explaining to the AI: how your deploy works, a pricing decision and its rationale, a vendor comparison. Not for: work in progress (Task) or per-service operational info (Integration).

A Note folder is one topic, with a note.md and any supporting files:

note.md:
---
type: Note
title: <topic>
---
The knowledge itself. Write to be grepped: headings and keywords over prose.

Rendering

No component by default; instances show as file cards. Add /_components/note.jsx to customize.

Report (folder)

A recurring output: one definition of what to produce, plus dated runs.

Use it for: anything generated repeatedly: weekly metrics, a monthly billing summary, a daily error digest. Pairs well with a /_commands/ script that writes the run file. Not for: one-off analysis (put it where it was asked for) or evolving knowledge (Note: edited in place, not dated).

A Report folder has a report.md and a runs/ folder:

report.md:
---
type: Report
title: <what this reports on>
---
What this report shows, and how it is produced (which script or command
generates a run).

Each run is runs/YYYY-MM-DD.md; the newest file is the current truth, older ones are history.

Rendering

No component by default; instances show as file cards. Add /_components/report.jsx to customize.

Contact (folder)

A person or organization you work with, plus the running log of interactions.

Use it for: clients, vendors, collaborators: anyone the AI should have context on before you draft the next email. Not for: one-off mentions; only create a Contact you expect to come back to.

A Contact folder has a contact.md and an optional log.md:

contact.md:
---
type: Contact
title: <person or company>
kind: person | company
---
Who they are, why they matter, and the current state of the relationship.

log.md is one dated bullet per interaction, newest first.

Rendering

No component by default; instances show as file cards. Add /_components/contact.jsx to customize.

Workflow (folder)

A reusable procedure the AI runs many times, that improves itself: playbooks hold what it has learned, logs hold what it has done.

Use it for: recurring operational work with a queue behind it: support tickets, refund requests, onboarding runs, incident triage. The docs site has a step-by-step guide for building a support workflow on this type. Not for: one-off work (Task) or a procedure with no execution history worth keeping (Note).

A Workflow folder has a workflow.md, a steps.md, a playbooks/ and a logs/ folder:

workflow.md:
---
type: Workflow
title: <short title>
---
## Purpose
What this workflow resolves and when to trigger it.

## How to run
Follow steps.md; read the relevant playbooks/ doc before executing.

steps.md       the phase-by-phase procedure the AI follows on every run
playbooks/     one markdown doc per recurring scenario, plus an llms.txt index
logs/YYYY-MM/  one log per run ({id}-{slug}.md), plus an llms.txt index per month;
               logs/llms.txt lists the months

After each run, add the log and update the month's llms.txt. When a run teaches something new, fold it back into the matching playbook, or create one (generalize IDs to {placeholders}). Logs are historical records: never rewrite old ones.

Rendering

No component by default; instances show as file cards. Add /_components/workflow.jsx to customize.