# Help

Short how-tos, each a few steps. Pick what you want to do; the guides below go deeper.

```cards
🤖 | Your AI agents | [[Help:Agents]] | Running agents by role, watching them, guardians
🔐 | Permissions | [[Help:Permissions]] | What your AI may do on its own, and what waits for you
🗝️ | Vault | [[Help:Vault]] | Secrets for your AI agents
📋 | Pipeline | [[Help:Pipeline]] | The list of work, by role
🗂️ | Projects | [[Help:Projects]] | Creating one, members, roles and permissions
🧭 | System view | [[Help:SystemView]] | Each feature you asked for: built and checked
🔬 | System view (pro) | [[Help:SystemViewPro]] | Spec, design, implementation and tests side by side
🧮 | Expressions | [[Help:Expressions]] | The expression language by example
⚙️ | Settings | [[Help:Settings]] | Everything you can set, on one page
🔄 | Dev-sync | [[Help:DevSync]] | Pages that follow changes while you work
🧠 | ESP (Mind Meld) | [[Help:ESP]] | Your AI takes you to the page you're talking about
✅ | Work | [[Help:Work]] | To-dos and pipeline items side by side
🚀 | Init | [[Help:Init]] | The init page, lifecycle messages, crons
📝 | Obsidian | [[Help:ObsidianSync]] | Keep an Obsidian vault and d2 in step
💡 | Example prompts | [[ExampleAiPrompts]] | What to ask your AI, and what came back
🛠️ | Agent hints | [[AgentHints]] | Quirks of this build an AI agent should know
```

All help topics: [Help](/topics?category=Help).

## Connect your AI {#connect-your-ai}

Your AI reads and writes your project for you: the wiki, your memories, the data and its model. You never copy a token.

1. **Let your AI reach d2.** Allow your d2 address in your AI's network settings: the domain your project is on, with `*.` in front (for example `*.ai-putty.com`). In Claude: the allowed domains for code execution, in your settings or your project.
2. **Get your line.** On your project's home, under **Onboard your AI**, press **Done**, then **Copy**. The line works once, for 10 minutes.
3. **Paste it into your AI chat.** Your AI connects itself and keeps its access somewhere private. The card on your home turns green: *Your AI is connected*.
4. **Try it.** Ask *"list the topics in my d2 project"*. Its first job is usually *"remove the onboarding section from my home page"*.
5. **Let it remember.** Ask *"remember in d2 that I follow copper producers"*: it appears under [memories](/topics?category=Memory), where you can correct it.

- **The line ran out, or was used?** Press **New AI invite** for a fresh one.
- **Using Claude Code or Claude Desktop?** You can install d2-connect instead: on [AI tokens](/ai/tokens), press **Download d2-connect** and add it to your AI as a skill.
- **After the first 7 days:** [renew your token safely](#renew-your-token-safely).

## Renew your token safely {#renew-your-token-safely}

Your AI's access lasts **7 days** at first, then **30 days** at a time. A couple of days before it ends, your AI tells you.

1. **Open AI tokens:** from the notice d2 sends you, or user menu → **Settings** → **AI permissions** → **AI tokens** ([/ai/tokens](/ai/tokens)). Press **Give my AI a new token**.
2. **Tell your AI: *"get your new d2 token"*.** It fetches the new one itself and switches over; the old one stops working at that moment.

**Already ended, or your AI can't fetch it?** Open the fold under the button, copy the line it shows and paste it into your AI chat within 10 minutes.

- **Where your AI keeps it:** in its project settings, or its memory, so it doesn't need a new invite every chat. With neither, press **New AI invite** on your project's home for each new chat.
- **To stop an AI:** your AI's tokens are listed under yours on AI tokens, each with **Revoke**. Revoking yours ends all of them at once.

## Keep your AI away from a page {#if-you-dont-want-your-ai-to-access-or-edit-things}

Add one line to the top of the topic, with its other properties:

- `ai-access: no`: hidden from AI tokens completely (not readable, not changeable, not even listed or found in search).
- `ai-access: read`: your AI can read it but not change it.

It only limits AI tokens: people on the project see and edit it as before, and only a person can add, change or remove the line.

## Keep work in the pipeline {#keep-work-in-the-pipeline}

The **Pipeline** (on your Home, and in the Toolbox) lists work waiting on the project: ideas you parked, questions for you, work passed between you and your AI agents. Say *"park it"* to your AI about an idea and it becomes an item. More: [[Help:Pipeline]].

## See what your AI agents are doing {#see-what-your-ai-agents-are-doing}

Running several AI agents on a project? Each posts to **Agents** (in the Toolbox):

- **its state:** up, idle, working, waiting, done, stuck, gone;
- **what it's on and what it changed;**
- **a graph** of what each waits on and sends to the others.

You get a notice when one is stuck, keeps hitting its limits, or goes quiet. Agents only talk to each other, never to another person's; they write a memory only when you tell them to; a change to a skill waits in your Drafts. When one needs your OK, it leaves an approval in the Pipeline to **Approve** or **Refuse**.

## Create a project {#create-a-project}

1. **Name it.** Your first time, type a name under **Make your first project**. After that: user menu → **My projects** → **New project**. Lower-case letters, digits and dashes; it becomes the address, `<name>.<your d2 domain>`.
2. **Pick its kind:** **Hero** (your own app, no code), **Creator** (you model and build) or **Pro** (the full kit: fiddle, flows, API). You can change it later in **Settings**.
3. **It's yours:** you're its owner and admin. Visitors see its landing page.
4. **Who can join:** **Settings** → **Project**: **request** (people ask, an admin approves; the default), **open** (anyone) or **invite** (only people an admin adds). Invite someone by email on **Settings → Members**.
5. **Bring your AI:** see [Connect your AI](#connect-your-ai).

## Write a wiki topic {#write-a-wiki-topic}

1. **Start it:** open the [Wiki](/topics) and press **New topic**. Names are letters, digits, `-` and `_`, no spaces.
2. **Write markdown** on the left; the preview on the right follows as you type.
3. **Save** (or ⌘/Ctrl + S). You need to be logged in; if you aren't, you're taken to **Log in** and back.

- **Links:** `[[Frostline]]` for a topic, `[[Company:FLR]]` for an object, `[[Frostline#Drilling plan]]` for a section (or `[[#Drilling plan]]` on the same page). A link to a missing topic shows red: click it to create it. Every heading has a ¶ to copy its address; add `{#name}` to a heading to keep its address when you rename it.
- **Edit one section:** press the faint **✎ edit** by its heading, or `e` while you read it. **Save** or **Cancel** brings you back there.
- **Watching your AI work?** Turn on dev-sync (the circling arrows in the top bar): the page shows your newest draft and reloads itself on any change.
- **Delete:** open it, **Edit** → **Delete**. It stays in **Settings → Trash** for 30 days; **Revive** brings it back.
- **Reports** are one-off answers written as pages: out of search and the wiki, found from their link or the **Reports** chip. A page tagged `#ephemeral` keeps no history and has **Dismiss** (gone for good).

## Add a class to the domain {#add-a-class-to-the-domain}

1. Open [[mining-domain]] and press **Edit**, or write a `Spec:` topic of your own.
2. Add a line such as `$class Drone (@key id: String, @label name: String, owner: <>Company)`.
3. **Save.** The class appears in the [model graph](/domain/overview) and the [object browser](/dom).
4. **Problems?** The save lists them, and so does the object browser's home. Rules: [[Skill:domain-modelling]].

## Add or edit an object {#add-or-edit-an-object}

1. Open the class in the [object browser](/dom), for example [Company](/dom/val/Company).
2. Press **New Company**, or open an object and press **Edit**.
3. Fill in the form, press **Review changes**, then **Save**. Fields marked `?` in the class can stay empty.

## Add an image or a file {#add-an-image-or-a-file}

1. **Pick files:** open **Files** in the menu. Images (png, jpg, gif, webp), pdf, or text (txt, md, csv, json, yaml…), up to 5 MB each.
2. **Tag them** (that's how you find them again). **Members only** starts ticked: untick it for a file anyone may see, like a logo.
3. Press **Upload**, then **Copy markdown** on the file and paste it into a topic.

- **Limits:** set by the owner's plan (free: 20 files, 5 MB in all); the Files page shows what's used.
- **Safe by design:** files are served from `cdn.aidieselapps.com`, a separate address, so a file can never act as a page of your project. Your AI can upload them too.

## Try an expression {#try-an-expression}

1. Open the [Fiddle](/fiddle).
2. Type one expression per line, e.g. `[1, 2, 3] map (x => x * 2)`, or `name = value` to use it on later lines.
3. Results show on the right. **Load an example** shows what the language can do.

## Write a rule and run it {#write-a-rule-and-run-it}

1. **Open the rule:** the [Fiddle](/fiddle?tab=specs&topic=Spec:hello), **Specs** tab: [[Spec:hello]] answers the message `hello.greet`.
2. **Change it,** e.g. the greeting to `"Hi, ${name}!"`. It's checked as you type. **Save**.
3. **Run its story:** **Stories** tab, [[Story:hello]]. It sends the message and checks its `$expect` lines; the one you just broke shows ✗ with what it got.
4. **Fix the `$expect`** to match; it runs again as you type. Save it too.

More: [[Story:order]] (guards, a discount, a rejected order) and [[Story:alerts]] (lists, notifications, shared values). Runs never change your data.

## Show data in a table {#show-data-in-a-table}

1. Edit any topic and add a block:
   ````
   ```table
   class: Holding
   columns: company, shares, company.price as Price, value
   totals: value
   sort: value desc
   ```
   ````
2. **Save.** The table shows the objects as the page loads (reload for new data); each row opens its form, **+ Add** makes a new one.

Columns can follow a reference (`company.price`); computed fields (`@calc` in the class) work like any other. More: [[Skill:d2-maker]].

## Make an app {#make-an-app}

An app is a page with a free hand: your own HTML, CSS and scripts, reading and writing the project's data. The easy way: ask your AI *"make an app that shows …"*.

1. **Make it:** in the [Wiki](/topics?category=App) under **apps**, press **New**. An app is an `App:` topic holding a whole HTML page.
2. **Use your data** in its script with `d2.api`, as whoever is looking at it:
   ```
   const list = await d2.api("GET", "/api/v2/dom/Holding")
   await d2.api("POST", "/api/v2/diesel/run", { story: "$send market.refresh", scratch: false })
   ```
3. **Open it** at `/app/<name>` (the topic has **Open the app**), and link it from your home with a card: `📈 | My app | /app/<name> | what it does`.

- **Framed or full page:** it opens under the top bar by default. `layout: full` in its frontmatter gives it the whole window, with a small ⌂ home.
- **Safety:** an app runs sandboxed and reaches the project only through `d2.api`. A full-page app runs with the viewer's login: only let people you trust edit one.

## Add a live widget {#add-a-live-widget}

For a small live piece inside a page (prices from the web, a chart), put HTML and a script in an ` ```embedhtml ` block. It runs in a sandbox, takes the page's colours and fonts, sizes itself, and can fetch from sources that allow any site. d2portfolio's market cards are one.

## Make your own stylesheet {#make-your-own-stylesheet}

Your AI can make you a new look; a stylesheet is just a `Style:` topic.

1. **Ask:** *"In d2, make me a stylesheet called yahoo: the logo says YAHOO, the background is dark green and the fonts are magenta."*
2. **It checks its work:** it saves `Style:yahoo` and fixes anything d2 reports.
3. **Pick it:** [Styles](/styles) → **Style topics** → **Use this stylesheet**.
4. **Tweak it:** ask (*"make the links yellow"*) or edit its `style` block; reload to see it.
5. **Go back:** **Use this stylesheet** on stylesheet-orange1, the default.

## Start over {#start-over}

1. Go to [Home](/home) and press the red **Reset all**.
2. Confirm. The demo data and every wiki topic go back to how they started; everything you added is gone, your Style topics included.

## When things go wrong {#when-things-go-wrong}

- **"write needs a bearer token" or `E_AUTH`:** the token is missing or wrong. In a browser the page asks again; for your AI, see [Renew your token safely](#renew-your-token-safely).
- **Your AI says its token ended, expired or revoked:** [Renew your token safely](#renew-your-token-safely).
- **Your AI says the connection is blocked:** your d2 address isn't allowed in its network settings yet (step 1 of [Connect your AI](#connect-your-ai)).
- **`E_VALIDATION` saving an object:** the message names each field that doesn't fit; fix those and save again.
- **A stylesheet shows "Has errors"** on [Styles](/styles): the list under it says which lines; fix them, or ask your AI.
- **Your changes vanished:** demo projects reset on every deploy and on **Reset all**. Keep your work in a project of your own.
- **Something else:** every page has a twin in the API: put `/api/v2` in front of the path to see the raw data, e.g. [/api/v2/dom/val/Company:FLR](/api/v2/dom/val/Company:FLR).