# wander.md skill: work on notes

wander.md hosts markdown notes. The api is https://api.wander.md.
There are two kinds of access.

## a quick vault someone shared with you (no key needed)

A url like https://wander.md/7k2m9xfq4w3nt8 is the page a PERSON opens. That
last segment is a whole VAULT, made without an account, and holding the name IS
the credential: no signup, no api key. It holds one note to start with and can
hold more files beside it. The api door for that note is:

    https://api.wander.md/v1/vaults/7k2m9xfq4w3nt8/files/note.md

Read it (raw markdown; `etag` carries the content hash, `x-wander-mode` is
view | edit | agents):

    curl -i https://api.wander.md/v1/vaults/{name}/files/note.md

`?meta=1` returns json instead: {markdown, contentHash, mode}.

Write the whole note:

    curl -X PUT https://api.wander.md/v1/vaults/{name}/files/note.md \
      -H 'content-type: text/markdown' \
      -H 'x-wander-agent: your-agent-name' \
      -H 'x-wander-instruction: what the human asked for' \
      -H 'x-wander-base: {the etag you read}' \
      --data-binary @note.md

Or as json: PUT {markdown, base, agent, instruction}.

Change ONE part of it, without holding the rest. Read the map first: it lists
what can be addressed and the version token to quote back.

    curl 'https://api.wander.md/v1/vaults/{name}/files/note.md?format=map'
    → {path, version, headings:[{path,depth}], anchors, frontmatter, blocks}

    curl -X PATCH https://api.wander.md/v1/vaults/{name}/files/note.md \
      -H 'content-type: application/json' \
      -d '{"at":"Plan::Week 1","kind":"heading","op":"append",
           "content":"- ship the thing\n","if_match":"blake3-..."}'

    kind: heading | anchor | frontmatter | doc
    op:   append | prepend | replace | delete

A heading address is the path the map printed, joined by `::`
("Plan::Week 1"). Use the map's strings verbatim rather than building them.

Everything you did not address comes back byte-identical.

Rules that matter:
- send `base` (on PUT) or `if_match` (on PATCH) = the hash you READ. On PUT,
  a stale base 3-way block-merges with whoever edited meanwhile: nothing is
  clobbered, and a true same-block conflict answers 409 with the current
  markdown. On PATCH a stale token answers 409 and writes nothing.
- `x-wander-agent` is your name; `x-wander-instruction` is WHY you are
  editing. Both land in the note's history, and your edit appears LIVE in any
  open editor, attributed to you.
- a view-only link refuses writes (403). Respect `x-wander-mode`: only
  `agents` links invited you; `edit` links permit writes but were shared
  person-to-person.
- notes are capped at 1MB, attachments at 10MB; unclaimed notes are deleted
  after 30 days.

It is a vault, so it holds whatever you put in it:

    GET https://api.wander.md/v1/vaults/{name}/files              list them
    PUT https://api.wander.md/v1/vaults/{name}/files/findings.md  another note
    PUT https://api.wander.md/v1/vaults/{name}/files/attachments/x.png

PUT takes json {markdown} or the raw bytes. Reference attachments from markdown
RELATIVELY: `![](attachments/x.png)`. Every file you write is visible on the
vault's own page, so a human sees what you produced.

These are the SAME routes a signed-in vault uses, one segment shorter, because a
quick vault's name holds exactly one vault:

    /v1/vaults/{name}/files/{path}                  the url IS the credential
    /v1/vaults/{username}/{vault}/files/{path}      Bearer sk_

## a signed-in vault (accounts, sk_ tokens)

Vault owners give agents real credentials via the auth.md protocol:
https://wander.md/auth.md - registration yields an sk_ bearer token.

    GET    /v1/vaults/{username}/{vault}/files              list files
    GET    /v1/vaults/{username}/{vault}/files/{path}       read one
    GET    /v1/vaults/{username}/{vault}/files/{path}?format=map
    PUT    /v1/vaults/{username}/{vault}/files/{path}       write it
    PATCH  /v1/vaults/{username}/{vault}/files/{path}       addressed edit
    DELETE /v1/vaults/{username}/{vault}/files/{path}
    GET    /v1/account                                      who you are

Authorization: Bearer sk_... on every request. The map and patch shapes are
identical to a note's, so code written for one works on the other.