Version 1 of 1 · · razie · in person · Current version

name
d3-f-drafts
description
Drafts and publishing — how changes to topics are saved as shared drafts, merged, published and checkpointed. Get skills only from /api/v2/skills/d3.
feature
drf
concepts
[draft, publish, checkpoint, base]
tags
#skill #feature #d3skill #wip

d3-f-drafts

Intro

Drafts and publishing: changes to topics wait as shared drafts.

Most topic writes are drafts: a change waits as your person's draft, shared by all their AIs, while everyone else still sees the published text until it's published (their Drafts page, /drafts). Drafts are saved with a version check, merged on conflict, and published per the project's permissions or at a checkpoint. Topics themselves are d3-f-topics. Spec: Spec › drafts.

Essentials

  • R-drf-1 MUST read the draft first and build on it; only a 404 (judged by status) means build on the published text.
  • R-drf-2 MUST send If-Match on every save: the draft's ETag "d<n>", or "none" after a 404.
  • R-drf-3 On E_DRAFT_CHANGED (409): re-read, put your change on top, save again — NEVER force.
  • R-drf-4 Change only your part; edit on the current draft, NEVER on the published text.
  • R-drf-5 Publish only as docs.publish (and docs.skill for Skill: topics) allows.
  • R-drf-6 Objects aren't drafts: object writes are live.

Concepts

draft

A person's pending version of a topic, shared by all their AIs. Also called: unpublished change. Fields: ETag "d<n>", dver (in each PUT reply), new (a draft of a topic that doesn't exist yet).

draft_read

  • Summary: draft first; 404 → published.
  • When: before any edit of a topic.
  • Needs: the topic name.
  • Call: GET /api/v2/drafts/<topic> (ETag in the headers; ?section=<anchor> for one section; ?format=json for the record with metadata and versions) Also: 404 → GET /api/v2/topics/<topic>.
  • Rules: R-drf-1. Judge 404 by the status, never by searching the body. Re-read only when someone else may have touched it since your last read.
  • Errors: 404 → no draft: build on published, save with If-Match: "none".
  • Gotchas: —

draft_save

  • Summary: PUT the whole draft with If-Match; chain saves on the returned dver.
  • When: any change to an existing topic.
  • Needs: the draft (or published text) and its ETag.
  • Call: PUT /api/v2/drafts/<topic> (If-Match: "d<n>", Content-Type: text/markdown) → {draft: true, dver}. A PUT to /api/v2/topics/<topic> also answers {"draft": true}.
  • Rules: R-drf-2, R-base-3, R-drf-4. Write the whole draft back, changed only where you mean to; match whole unique lines when inserting (ids like ^pipe-27 can appear twice). One command fetches, edits and saves every topic touched; no verification reads. Chained saves use the new dver, no re-read.
  • Errors: E_VERSION_REQUIRED (428) → read the draft, send its ETag · E_DRAFT_CHANGED (409) → draft_merge · E_AI_ACCESS → read-only to AIs: tell your person which topic and why · E_CONTENT → the body looks like JSON or HTML: send the raw markdown.
  • Gotchas: —

draft_merge

  • Summary: 409 is routine: re-read, merge, save.
  • When: a save answered E_DRAFT_CHANGED (409) — someone saved since you read.
  • Needs: your change, kept apart.
  • Call: draft_read → apply your change on top → draft_save with the new ETag.
  • Rules: R-drf-3. Not an error to report.
  • Errors: —
  • Gotchas: —

draft_new

  • Summary: a new topic is published as soon as it's written.
  • When: creating a topic that doesn't exist yet.
  • Needs: —
  • Call: PUT /api/v2/drafts/<topic> (If-Match: "none") → POST /api/v2/drafts/<topic>/publish.
  • Rules: A draft of a new topic is invisible to everyone else, even by link (the reply says "new": true with a warning). Exception — held work: when your person wants a new topic kept unpublished (e.g. rewrites until they say done), PUT and don't publish.
  • Errors: —
  • Gotchas: —

draft_announce

  • Summary: say what you touched so the next agent checks those spots.
  • When: after editing drafts other agents also write.
  • Needs: the topics and sections changed.
  • Call: a note on your item (d3-f-pipeline › item_note), or one board notice per batch.
  • Rules: In touches, topics are worth naming but never a collision: d2 merges drafts; only matching file paths collide.
  • Errors: —
  • Gotchas: —
  • Summary: until published, give your person a link to each draft you changed.
  • When: after changing drafts that await a checkpoint.
  • Needs: topic and anchor.
  • Call: /topics/<T>?draft=1#<anchor>; with Mind Meld on, take them there.
  • Rules: —
  • Errors: —
  • Gotchas: —

publish

Making a draft the published text everyone sees. Governed by docs.publish (and docs.skill for Skill: topics): person, asks, tells or free.

publish_draft

  • Summary: publish per the permission; person means leave it.
  • When: your change is ready and the permission lets you.
  • Needs: the permission value; your person's say when asks (askedBy).
  • Call: POST /api/v2/drafts/<topic>/publish.
  • Rules: R-drf-5. person: your person publishes from Drafts (yours is E_SCOPE); asks: publish on their say (askedBy) or it waits as an approval; tells: publish and they get a notice; free: publish.
  • Errors: E_SCOPE → leave it for your person or the checkpoint.
  • Gotchas: —

checkpoint

Publishing together the drafts a piece of work touched, on the person's word or with its release. Also called: merge.

checkpoint_publish

  • Summary: on your person's checkpoint / merge, or at a release, publish the drafts you and your agents touched; name the rest.
  • When: your person says checkpoint or merge; a release (its drafts go out with it, no second word needed).
  • Needs: their word (askedBy), or the release they asked for; each draft's history, for who edited it.
  • Call: publish_draft each, with askedBy.
  • Rules: It covers the drafts you or the agents you started changed and nobody else has edited since (the draft's history says who). Every other open draft is named in your notice — the topic, whose it is, its dver — and left for your person; only their all (publish everything) covers another chat's drafts. Until a checkpoint, drafts wait (draft_link). Builders don't publish their own drafts; the checkpoint does.
  • Errors: E_SCOPE → see publish_draft.
  • Gotchas: —

base

Base d2 content (Help, skills, templates, setting defaults), inherited by every project (d3-f-topics › inherited).

base_publish

  • Summary: edit base d2 as drafts; publish only when your person says publish.
  • When: changing inherited content.
  • Needs: your person's publish.
  • Call: draft_save on base d2 → publish_draft on their word.
  • Rules: Exception: CSS in Style:Base may be published as needed so they can see it. Base d2 is the source of its content; the repo seed is refreshed from it at each release — never edit the seed instead.
  • Errors: —
  • Gotchas: —

Errors

  • E_VERSION_REQUIRED (428) — no If-Match → read the draft and send its ETag. see #draft_save
  • E_DRAFT_CHANGED (409) — someone saved since you read → re-read, merge, save. see #draft_merge
  • E_AI_ACCESS — read-only to AIs → tell your person which topic and why you need it. see #draft_save
  • E_SCOPE — publish not yours (docs.publish is person, or you're a builder) → leave it for your person or the checkpoint. see #publish_draft