Version 28 of 41 · · Current version

Help

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

Guides, one topic each: Projects (creating one, members, roles and permissions), SystemView (the system view on hero and creator projects: each feature, what you asked for, and whether it's built and checked), SystemViewPro (the full view on pro and master: spec, design, implementation and tests side by side), Expressions (the expression language by example, and every core function), Pipeline (the list of work, by role), Agents (running AI agents by role, watching them, guardians), AgentHints (the quirks of this build an AI agent should know), Permissions (what your AI may do on its own, and what waits for you), Vault (secrets for your AI agents), Init (the init page: what it is, the lifecycle messages it handles, declaring crons, examples), LifecycleMessages (what d2 tells your project as things happen) and InitExample (an init page that uses them). All help topics: Help.

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 d2-connect 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 Settings from your user menu in the project, then AI permissions (or go to /ai), 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 d2-connect, once. On the AI tokens tab press Download d2-connect and add the file to your AI as a skill (in Claude, upload it as a skill); then paste the line under the button into your chat, with your token. d2-connect has your AI fetch the right skills for its role and your project's level at the start of every session (d2-maker first), so nothing on your machine goes stale.
  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, where you can read and correct it.

If something goes wrong, see When things go wrong.

If you don't want your AI to access or edit things

Add one line to the top of the topic, with the other properties: ai-access: no hides the topic from AI tokens completely (they can't read it, change it, or even see that it exists, in lists, search or the system view); ai-access: read lets your AI read it but not change it. Without the line, your AI can read and edit the topic as usual. The setting only limits AI tokens: you and the other people on the project see and edit the topic as before, and only a person can add, change or remove the line.

Keep work in the pipeline

The Pipeline (on your Home, and in the Toolbox) lists the work waiting to be done on the project: ideas you parked, questions for you, and work passed between you and your AI agents. Say "park it" to your AI about an idea and it becomes an item. How it works, with a diagram: Pipeline.

See what your AI agents are doing

If you run several AI agents on a project, each posts what it's doing to Agents (in the Toolbox): its state (up, idle, working, waiting, done, stuck, gone), what it's on, what it changed, and a graph of what each one waits on and sends to the others. You get a notice when one is stuck, keeps hitting its limits, or goes quiet. Your agents only talk to each other, never to another person's; they write a memory only when you tell them to, and a change to a skill waits in your Drafts for you to publish. When an agent needs your OK and you're not in the conversation, it leaves an approval in the Pipeline for you to Approve or Refuse.

Create a project

  1. Log in, open Home (your projects), and type a name under New project: lower-case letters, digits and dashes. It becomes the address, <name>.aiheroapps.com.
  2. Pick what kind of project it is: Hero (your own app, no code), Creator (you model and build) or Pro (the full kit: fiddle, flows, API). It sets the menu and the home page you start with; you can change it later in the project's Settings.
  3. You're its owner and admin, and it opens on its home page. Its public page (the landing) is what visitors see.
  4. Who can join: open Settings in your user menu, then Project (under This project), and choose request (the default: people ask, an admin approves), open (anyone can join) or private (members only: visitors see at most the landing page, and only people an admin adds get in). Invite someone by email on Settings → Members; the invite works whatever the setting.
  5. Bring your AI: make it a token on the project's Tokens page, see Connect your AI.

Write a wiki topic

  1. Open the Wiki 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. Link a section of a topic with [[Frostline#Drilling plan]], or one on the same page with [[#Drilling plan]]; every heading has a ¶ you can copy its address from. Add {#name} at the end of a heading to give it an address that stays put when you rename it. When an AI is working on your pages, turn on dev-sync (the circling arrows in the top bar): a topic or app you're looking at then shows your newest draft of it and reloads itself within two seconds of any change; the editor never reloads.
  4. Press Save (or ⌘/Ctrl + S). The first save asks for the write token.
  5. To change one section, press the faint ✎ edit beside its heading, or press e while you read it: the editor opens at that line, highlighted, with the cursor there. Save or Cancel takes you back to the same section, which flashes.
  6. To delete a topic, open it, press Edit, then Delete. It goes to the trash for 30 days, with its history: open Settings → Trash and press Revive to bring it back.

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

Add or edit an object

  1. Open the class in the object browser, for example 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: images (png, jpg, gif, webp), pdf, or text (txt, md, csv, json, yaml and other text files), up to 5 MB each.
  2. Add a few tags (they're how you find files again). Members only is ticked to start with: untick it for a file anyone may see, like a logo on a public page.
  3. Press Upload, then Copy markdown on the file and paste it into a topic.

How many files a project can have depends on its owner's plan: on the free plan, 20 files and 5 MB in all; the Files page shows how much is used.

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.
  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 and pick the Specs tab. 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 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 order (guards, a discount, a rejected order) or alerts (lists, notifications, shared flow values). Runs never change your data.

Show data in a table

  1. Edit any topic (a home page, a notes page) and add a block:
    ```table
class: Holding
columns: company, shares, company.price as Price, value
totals: value
sort: value desc
```
  2. Save. The table is drawn with the page: it shows the objects as they are when the page loads (reload for new data); each row opens its form, and + Add makes a new one.
  3. Columns can follow a reference (company.price) and computed fields work like any other (@calc in the class, see d2-maker).

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.

  1. Open the Wiki under apps and press New, or ask your AI to "make an app that shows …". An app is an App: topic holding a whole HTML page.
  2. In its script, get and save data 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. Save, and open it at /app/<name> (the topic has an Open the app button). Link it from your home page with a card: 📈 | My app | /app/<name> | what it does.
  4. Framed or full page: by default an app opens under the top bar and scrolls inside it. Add layout: full to its frontmatter to give it the whole window (a console, something for your phone's home screen); a small ⌂ button leads back.
  5. For now a full-page app runs as whoever opens it, with their login: only let people you trust edit one.

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, and sizes itself; it can fetch from sources that allow any site. d2portfolio's market cards are one.

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.

  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, 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 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).
  • 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: 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.