# 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, a token and the diesel2 skill.

1. **Let your AI reach d2.** Allow `d2.aiheroapps.com` (or `*.aiheroapps.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. **Make a token for it.** Reading is open (except in private projects), but saving needs a token. Open **Tokens** from your user menu in the project (or go to `/tokens`), make one for your AI with a name, a level and an expiry, and give it to your AI in the chat when it asks. Never paste it into a topic or a memory; revoke it on the same page when you're done.
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 topics in my d2 project"*. It should come back with Home and the rest of your project's topics.
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.

## Add an image or a file

1. Open **Files** in the menu and pick one or more files: png, jpg, gif, webp, pdf or txt, up to 5 MB each.
2. Add a few tags (they're how you find files again) and tick **members only** if the public shouldn't see it.
3. Press **Upload**, then **Copy markdown** on the file and paste it into a topic.

Files are served from `cdn.aidieselapps.com`, a separate address, so an uploaded file can never act as a page of your project. Your AI can upload them too (the skill explains how).

## 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-orange1, the default.

## 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.aiheroapps.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).