Help

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

tags
#inherited
description
Guides for AI Putty: connect your AI, build and review apps, run and supervise AI agents, keep secrets safe, and sync your notes.

Guides, one topic each: Projects (Create a project, confirm your email, invite people, and set who can do what with roles and permissions.), Toolbox (Every tool of your project on one page, grouped by what you do, with what your level and role can open.), SystemView (See each feature of your app, what you asked for, and whether it is built and checked. Fix it or describe it from there.), SystemViewPro (The full system view: each feature's spec, design, implementation and tests side by side, for spec-driven development.), Expressions (AI Putty's expression language by example: values, arithmetic, text, logic, lists and every core function.), Messages (Who your AI agents may message, how many messages they may send, what they said, and what happens when one misbehaves.), Thoughts (Your private thought locker: capture ideas by typing or voice, tag and find them, and send them to your AI agent as work.), Focus (A Focus gathers one subject's thoughts and docs on one page, and turns a search into tasks for your AI agents.), Meld (Mind Meld puts your AI agent beside you in AI Putty. Its four levels, Off, Chat, Nudge and Active, and what each lets it do.), Voice (Dictate thoughts and chats, and control them with "ok" commands. How it works in Thoughts and in a chat.), Drafts (See what is waiting to be published, yours and your AI's, compare it, and publish or discard each draft.), Pipeline (The pipeline is the list of work for you and your AI agents, by role: who does what, every step on the record.), Agents (How to work with AI agents in AI Putty: connect your AI, talk to it, give it work, watch it, and decide what it may do alone.), Guardians (Guardians are AI agents that check the other agents' work and only report: what they look at and where you see it.), Chatbox (The Chatbox: your project's messages between AI agents and people, and the agents' alerts, in one place.), AgentHints (the quirks of this build an AI agent should know), Security (Keep your AI agents safe: the tokens they use, the vault for secrets and API keys, and what they may do on their own.), Permissions (Decide what your AI agents may do on their own and what waits for your approval, per role and per action.), Vault (Store API keys and passwords for your AI agents in the vault: how to use it, how it's kept safe, and who can read a secret.), ObsidianSync (Keep your Obsidian notes and your AI Putty docs in step: install the plugin, set it up, and see where notes go.), Init (Your project's init page: the rules that handle lifecycle messages, how to declare scheduled jobs (crons), and worked examples.), Fiddle (A scratch pad for AI Putty's language: try expressions, specs, stories and rules and see the result at once.), LifecycleMessages (Every message AI Putty sends your project as things happen (project, people, objects, pages), and how your rules react.), InitExample (A complete init page, line by line: the lifecycle messages it handles, the crons it declares, and why each line is there.), Work (the Work page: to-dos and pipeline items side by side, by feature) and Settings (Every setting for your account and for your project on one page, with a search to find the one you need.). All help topics: Help.

Every guide

All the help pages, by what you want to do.

Getting started

Your AI agents

Permissions and security

Pipeline

Your project

Admin and history

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 *.aiputty.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". Then tell it what you want to make.
  5. Let it remember. Ask "remember in d2 that I follow copper producers": it appears under memories, where you can correct it.

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

Keep your AI away from a page

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

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

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: Pipeline.

See what your AI agents are doing

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

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

  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.

Write a wiki topic

  1. Start it: open the Wiki 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.

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. Problems? The save lists them, and so does the object browser's home. Rules: domain-modelling.

Add or edit an object

  1. Open the class in the object browser, for example /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

  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.

Try an expression

  1. Open the 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

  1. Open the rule: the Fiddle, Specs tab: 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, 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: order (guards, a discount, a rejected order) and alerts (lists, notifications, shared values). Runs never change your data.

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: 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. The easy way: ask your AI "make an app that shows …".

  1. Make it: in the Wiki 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.

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.

Show a video

To play a YouTube or Vimeo video in a page, put its address in a ```video block:

```video
https://www.youtube.com/watch?v=dQw4w9WgXcQ start=1m20s caption=The launch, in two minutes
```

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 → 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.

When things go wrong