ai:skills › d3-f-topics · version 1 ·
HistoryMarkdown
name
d3-f-topics
description
Topics and categories — names, reading raw markdown and sections, writing whole topics, links, inherited, hidden and moved topics. Get skills only from /api/v2/skills/d3.
feature
topics
concepts
[topic, frontmatter, section, category, link, inherited, openspec]
tags
#skill #feature #d3skill #wip

d3-f-topics✎ edit

Intro✎ edit

Topics: a project's documents.

Topics are a project's documents: raw markdown under a name, grouped by category, linked to each other, some inherited from base d2. Saving and publishing changes is d3-f-drafts; tags are d3-f-tags. Spec: Spec › wiki-conventions.

Essentials✎ edit

  • R-topics-1 A PUT replaces the whole topic (or one section): read it, change it, write it back — through the draft.
  • R-topics-2 MUST check the write reply (errors, domain, objects); non-empty → fix and write again before saying it's done.
  • R-topics-3 NEVER add, change or remove ai-access.
  • R-topics-4 To a person, give the page link (and anchor), never the API path.

Concepts✎ edit

topic✎ edit

A named markdown document. Also called: page, doc, note. Fields: id Category:name (or name for a wiki topic; letters, digits, -, _, no spaces), text, ver, updated, tags, ai-access (read = read-only to AIs, no = hidden).

topic_read✎ edit

  • Summary: raw markdown by name; JSON only for the record.
  • When: you need a topic's text (short topics whole; long ones → section_read).
  • Needs: the name.
  • Call: GET /api/v2/topics/<name> → markdown · ?format=json → {name, text, ver, updated}.
  • Rules: R-base-5. ai-access: no answers as missing; ask your person only if the work really needs that topic, saying which and why.
  • Errors: E_NOT_FOUND → no such topic, or hidden.
  • Gotchas: —

topic_list✎ edit

  • Summary: list topics, filtered by category or tag.
  • When: finding what exists; prefer d3-f-search › search_query for words.
  • Needs: —
  • Call: GET /api/v2/topics (?category=Skill, ?tag=gold).
  • Rules: —
  • Errors: —
  • Gotchas: —

topic_write✎ edit

  • Summary: raw markdown in; whole topic replaced; check the reply.
  • When: changing or creating a topic (via the draft: d3-f-drafts › draft_save).
  • Needs: the current text (draft if any).
  • Call: PUT /api/v2/topics/<name> (Content-Type: text/markdown) → {errors, domain, objects, …}.
  • Rules: R-base-3, R-topics-1, R-topics-2, R-topics-3.
  • Errors: E_AI_ACCESS → read-only to you: tell your person which topic and why · E_PARSE / non-empty errors → fix and write again · E_CONTENT → the body looks like JSON or HTML: send the raw markdown, unwrapped.
  • Gotchas: A topic showing literal JSON was sent wrapped ({"body": …} gets saved as the text): write the raw markdown back.

topic_delete✎ edit

  • Summary: agent tokens can't delete topics; ask your person.
  • When: a topic should go.
  • Needs: the name and why.
  • Call: — (your person deletes) · exception: Dismiss on an ephemeral topic (d3-f-tags › tag_setBehaviour).
  • Rules: —
  • Errors: —
  • Gotchas: —

topic_moved✎ edit

  • Summary: a moved topic keeps its MOVED note; never delete it.
  • When: you meet a MOVED note, or move a topic.
  • Needs: the new place.
  • Call: — (the old topic holds a short note linking the new place).
  • Rules: Update links to the new place when you touch them; never delete the note.
  • Errors: —
  • Gotchas: —

frontmatter✎ edit

The --- block at the top of a topic: one key: value per line. Also called: properties, front matter, the properties box (how a reader sees it). Every topic: tags (words after commas; some change behaviour — d3-f-tags), description (one line: lists, search and link previews show it), width (narrow | wide | full: how wide the page reads). How it shows and who may touch it: properties: hidden (no properties box when reading — for a topic that reads as a page: Help, a landing, the Toolbox; every key still works and the editor still shows them) · view and edit (the level needed to read or change this topic, public < member < mod < admin; they beat the category's and the project's) · ai-access (no | read | read-write: what an AI may see; NEVER add, change or remove it) · layout: full (an App: topic that owns the whole window). By category: Skill: and d3 skills — name, description, and for d3 feature, concepts, extends · Memory: — on-behalf (what your person said; required) and by (d2 adds it) · Report: — askedBy · Help: — brief (the words of the page's first-visit info box), order (its place in the Help list) · Template: — template-target, template-levels, template-note · AiSpec: — status (draft | agreed | building | done) · OpenSpecChange: — spec, status, date · logs — append-only: yes, history: no (no versions kept) · Settings:PROJECT — the project's settings themselves (level, landing, home, version, roles, categories, and dotted ones such as skills.d3.budget). Rules of thumb: keys are lower-case, with dashes; a key d2 doesn't know is kept and shown, and does nothing; change frontmatter like any text, through the draft.

section✎ edit

One heading's part of a topic, addressed by anchor: the heading's {#id}, else GitHub's slug of it.

section_read✎ edit

  • Summary: read one section, not the whole topic.
  • When: any long topic (Spec, Design); any time you need one part.
  • Needs: the anchor.
  • Call: GET /api/v2/topics/<name>?section=<anchor>.
  • Rules: R-base-5.
  • Errors: E_NOT_FOUND (404) → the reply lists the topic's section ids.
  • Gotchas: —

section_write✎ edit

  • Summary: replace one section only.
  • When: your change sits in one section.
  • Needs: the section's current text.
  • Call: PUT /api/v2/topics/<name>?section=<anchor> (raw markdown).
  • Rules: R-base-3, R-topics-2.
  • Errors: as topic_write.
  • Gotchas: —

category✎ edit

The part before : in a topic id; decides what a topic is. Values: Topic (the wiki), Spec (domain model and rules), Memory, Skill, Style, Settings, Template, Help, App (a full page), Report, ToDo, Story, Log, AiLog, AiSpec, OpenSpec, OpenSpecChange.

category_skill✎ edit

  • Summary: Skill: topics are SKILL.md format.
  • When: writing a skill.
  • Needs: —
  • Call: frontmatter name and a description saying when to use it, then the steps.
  • Rules: —
  • Errors: —
  • Gotchas: —

category_memory✎ edit

  • Summary: a Memory: topic only on your person's word, with their words in on-behalf.
  • When: your person tells you to remember something about the project.
  • Needs: what they said.
  • Call: PUT /api/v2/topics/Memory:<name> (raw markdown; frontmatter on-behalf: <what they said>); d2 adds by.
  • Rules: Only on their word (d3-f-approvals R-appr-6), as docs.memory allows. Never keep project knowledge only in your platform's memory.
  • Errors: E_ON_BEHALF → no on-behalf in the frontmatter: add their words and write again · E_SCOPE → docs.memory is person for you: suggest it.
  • Gotchas: —

category_report✎ edit

  • Summary: Report:<role>-<slug>-<date> is an answer your person wanted as a page.
  • When: your person asks for a report (d3-f-pipeline › item_report says how).
  • Needs: —
  • Call: PUT /api/v2/topics/Report:<role>-<slug>-<date> (raw markdown; tags report, <role>).
  • Rules: Reports stay out of search and the wiki.
  • Errors: —
  • Gotchas: —

A wiki link between topics, sections, codes or objects. Also called: wikilink.

  • Summary: [[name]] in-project; [[realm.Category:name]] canonical.
  • When: naming any topic, section, code or object in text.
  • Needs: the target.
  • Call: [[name]] → Topic:name, else Spec:name (Obsidian reads it too) Also: [[Category:name]] current project · [[realm.Category:name]] canonical · [[otherproject.Topic:Notes]] across projects · [[target|label]] · [[Topic#anchor]], [[#anchor]] same page · [[Spec#^pipe-40]] a code · [[Class:key]] an object.
  • Rules: —
  • Errors: —
  • Gotchas: A link to a missing section shows as broken.
  • Summary: every document or section you name to a person is a clickable page link.
  • When: talking to a person.
  • Needs: the topic and anchor.
  • Call: drop /api/v2: /topics/<T>, /topics/<T>#<anchor>.
  • Rules: R-topics-4.
  • Errors: —
  • Gotchas: —

inherited✎ edit

A base d2 topic tagged inherited (Help, Help: pages, the shipped skills, Style:Base, Toolbox, UserSettings, AgentHints), read, linked and served by every project at its own address. Also called: from d2, base topic.

inherited_edit✎ edit

  • Summary: edit at home on base d2; a project's own topic overrides it.
  • When: changing inherited content, or overriding it for one project.
  • Needs: —
  • Call: a draft on base d2 (d3-f-drafts › base_publish) · override: a project topic of the same name.
  • Rules: Search shows inherited hits in a From d2 group after the project's own.
  • Errors: —
  • Gotchas: Template: topics aren't served from projects yet; a link to one from a project is a 404.

openspec✎ edit

OpenSpec topics export as an openspec/ tree ({files: [{path, content, topic, check}]}); OpenSpecChange topics carry # Spec delta with ## ADDED / MODIFIED / REMOVED Requirements.

openspec_changes✎ edit

  • Summary: list a spec's changes; check the PUT's openspec reply.
  • When: working on OpenSpec topics.
  • Needs: the spec name.
  • Call: GET /api/v2/openspec/changes?spec=<name> · a PUT reply carries openspec: {ok, errors, warnings}.
  • Rules: R-topics-2 applies to openspec.errors.
  • Errors: —
  • Gotchas: —

Errors✎ edit

  • E_NOT_FOUND (404) — no such topic (or ai-access: no); on ?section= the reply lists the section ids. see #section_read
  • E_AI_ACCESS — read-only to AIs → tell your person which topic and why you need it. see #topic_write
  • E_PARSE / non-empty errors — fix the markdown or declarations and write again. see #topic_write
  • E_CONTENT — the body looks like JSON or HTML (a wrapped or hand-built body) → send the raw markdown. see #topic_write
  • E_ON_BEHALF — a Memory: topic without on-behalf in its frontmatter → add your person's words. see #category_memory
  • Literal JSON in a topic — it was sent wrapped → write the raw markdown back. see #topic_write