# Help

How-tos for the d2 prototype. Each one is a short list of steps; pick the task you want to do.

## Connect your AI

Your AI assistant can read and write this wiki, your memories, the domain and the objects through the API. It takes three things: network access, the write token and the diesel2 skill.

1. **Let your AI reach d2.** Allow `d2.aidieselapps.com` (or `*.aidieselapps.com`) in your AI's network or web-access settings. In Claude, that's the list of allowed domains for code execution in your project or workspace.
2. **Get the write token.** Reading is open to anyone, but saving needs the token. Ask whoever runs the prototype for it. Give it to your AI in the chat when it asks, and never paste it into a topic or a memory.
3. **Install the diesel2 skill.** Open [[Skill:diesel2]], press **Markdown**, and save the text as `SKILL.md` in a folder named `diesel2`. Add that folder to your AI as a skill; in Claude, zip the folder and upload it as a custom skill.
4. **Try it.** Ask your AI to *"list the d2 topics"*. It should come back with Welcome, the company topics and the rest.
5. **Let it remember.** Ask it to *"remember in d2 that I follow copper producers"*. A new entry appears under [ai:memories](/topics?category=Memory), where you can read and correct it.

If something goes wrong, see [When things go wrong](#when-things-go-wrong).

## Write a wiki topic

1. Open the [Wiki](/topics) and press **New topic**. Names are letters, digits, `-` and `_`, with no spaces.
2. Write markdown on the left; the preview on the right updates as you type.
3. Link a topic with `[[Frostline]]` and an object with `[[Company:FLR]]`. A link to a topic that doesn't exist yet shows in red; click it to create that topic.
4. Press **Save** (or ⌘/Ctrl + S). The first save asks for the write token.

## 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. If the save shows problems, fix them; the object browser's home page also lists the model checks. [[Skill:domain-modelling]] has the rules.

## 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**. Required fields must have a value; a field marked `?` in the class can stay empty.

## Try an expression

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

## Write a rule and run it

1. Open the [Fiddle](/fiddle?tab=specs&topic=Spec:hello) and pick the **Specs** tab. [[Spec:hello]] is open: a rule that answers the message `hello.greet`.
2. Change the greeting, for example `"Hi, ${name}!"`. The right side checks it as you type. Press **Save**.
3. Pick the **Stories** tab and [[Story:hello]]. It sends the message and runs its `$expect` lines; the one you just broke shows ✗ with what it got.
4. Fix the story's `$expect` to match, and it runs again as you type. Save it too.
5. For more, pick [[Story:order]] (guards, a discount, a rejected order) or [[Story:alerts]] (lists, notifications, shared flow values). Runs never change your data.

## Make your own stylesheet

Don't like the built-in looks? Your AI can make you a new one. A stylesheet is just a Style topic, so all it needs is [Connect your AI](#connect-your-ai).

1. **Ask your AI.** For example: *"In d2, make me a stylesheet called yahoo: the logo in the top bar says YAHOO, the background is dark green and the fonts are magenta."*
2. **Let it check its work.** It saves a topic `Style:yahoo`. If d2 reports problems with it, the AI fixes them and saves again.
3. **Pick it.** Open [Styles](/styles), find it under **Style topics** and press **Use this stylesheet**. Every page switches, the logo text included.
4. **Tweak it.** Ask for changes (*"make the links yellow"*), or open the topic and edit its `style` block yourself. Reload a page to see the result.
5. **Go back** any time: press **Use this stylesheet** on stylesheet-blue1.

## Start over

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

## 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, give it the token again.
- **Your AI says the connection is blocked:** `d2.aidieselapps.com` isn't allowed in its network settings yet (step 1 of [Connect your AI](#connect-your-ai)).
- **E_VALIDATION when saving an object:** the message names each field that doesn't fit the class. Fix those fields and save again.
- **A stylesheet shows "Has errors" on [Styles](/styles):** the list under it says which lines are wrong. Fix the topic, or ask your AI to.
- **Your changes vanished:** storage is in memory for now, so a redeploy, a restart or **Reset all** brings back the demo. Keep anything important somewhere else as well.
- **Something else:** every page has a twin in the API; add `/api/v2` in front of the path to see the raw JSON, for example [/api/v2/dom/val/Company:FLR](/api/v2/dom/val/Company:FLR).