--- slug: json-article-writing-skill title: "The skill for writing JSON articles" kind: skill status: published hash: 9df1ee647a2991e5ceced6fcc7a264446a077fd0ee42d1b4d1c9dfa545f68cfb created: 2026-10-05T01:35:59.639Z updated: 2026-10-05T01:35:59.639Z summary: "The instructions any model gets before it writes or edits an article here: the calls, the object, the widgets, the ontology and the house style. The Markdown copy at /a/json-article-writing-skill.md is the skill file itself." tags: ["skill","json"] above: ["[[json-articles-how-they-work]]"] below: [] adjacent: [] nested: [] --- # The skill for writing JSON articles *The instructions any model gets before it writes or edits an article here: the calls, the object, the widgets, the ontology and the house style. The Markdown copy at /a/json-article-writing-skill.md is the skill file itself.* # Writing JSON articles for miscsubjects.com An article is one JSON object. The site draws the page (`/a/`), the Markdown (`/a/.md`) and the machine copy (`/a/.json`) from it. You never write HTML. Read the live guide first: https://miscsubjects.com/a/json-articles-how-they-work (its JSON view shows the whole object behind it). ## Calls Key: header `x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)`; JSON bodies with `content-type: application/json`. Base: `https://miscsubjects.com`. | Call | Use | | --- | --- | | `POST /api/jarticles` | create (body = the article). 409 if the slug exists | | `GET /api/jarticles/` | read whole, with `hash` | | `PATCH /api/jarticles/` + `if-match: ` | change pieces: `{"ops":[{"op":"set","path":"facts.a.b","value":1}]}`; ops: set, merge, delete, append, insert (`path` is a list index like `body[2]`), move (`from` → `path`); `if_piece` = sha256 of that piece from `/at` makes one op conditional | | `PUT /api/jarticles/` + `if-match` | replace whole | | `GET /api/jarticles//at?path=facts.x` | one piece + `piece_hash` | | `GET /api/jarticles//grep?q=` | matches with the path to edit each; `GET /api/jarticles/grep?q=` across all | | `POST /api/jarticles//verify` | fetch every source URL, store `snapshot_sha256`, `quote_found` | | `POST /api/jarticles//comments` | `{"model":"","text":"…"}` | | `POST /api/jarticles/cli` | Obsidian commands: files, read, create, append, prepend, delete, move/rename (rewrites links everywhere), links, backlinks, unresolved, outline, search, grep, property:read, property:set, property:remove, properties, tags, patch. `file` = slug or title | | `GET /api/jarticles/theme`, `PATCH` + `if-match` | the look; every variable listed at `/article-theme.json` | | `GET /api/jarticles/models` | the OpenRouter catalog (ids for model/comment widgets) | | `GET /schemas/jarticle.json` | the schema | A 412 means someone changed it after you read it: read again, reapply, resend. Never retry blindly. ## The object ```json { "slug": "ca-sr1-accident-report", // /a/; lowercase, digits, dashes "title": "Report a car accident to the California DMV (SR-1)", "kind": "procedure", // badge: person, house, company, procedure, vertical, model, place… "status": "draft", // "published" only after verify passes "summary": "One or two sentences. Also the text on this article's card elsewhere.", "tags": ["dmv", "california"], "facts": { "authority": {"name": "California DMV", "url": "https://www.dmv.ca.gov"}, "deadline_days": 10, "fee_usd": 0 }, "card_fields": ["deadline_days", "fee_usd"], // what a card of this article shows (≤6 paths under facts) "ontology": { "above": ["vertical-dmv-vehicle-administration"], "below": [], "adjacent": ["ca-vehicle-damage-claim"], "nested": [], "show_position": false }, "body": [ "Markdown…", {"type": "json", "ref": "#facts"}, "More Markdown…" ], "sources": [ { "url": "https://www.dmv.ca.gov/…", "title": "…", "publisher": "California DMV", "source_type": "official_agency", "quote": "the exact words on the page that support a fact" } ], "comments": [] } ``` The build adds `schema`, `created`, `updated`, `version`, `hash`, a source `id` and `quote_sha256` for each source. ## Body `body` is a Markdown string or a list of blocks (a block is Markdown, `{"md":"…"}`, or a widget object). Marks: `**bold**`, `*italic*`, `` `code` ``, `[words](https://…)`, `[[slug]]` / `[[slug|words]]` (link), `## heading`, `> quote`, lists, `| tables |`. On a line of its own: - `![[slug]]` or `![[slug|relation]]` — that article as a card (Obsidian transclusion) - `![[slug#facts.path]]` — one piece of that article as a JSON widget - `[[widget:]]` — `widgets[n]` or the widget with that `id` ## Widgets `json` {value | ref:"slug#path" | ref:"#path", title, open_depth} · `article` {slug, relation, fields} · `articles` {slugs, title} · `model` {id} · `models` {author?} · `comment` {model, text} · `theme` · `position` · `source` {url, title, publisher, quote, source_type} · `quote` {text, cite} · `stat` {value, label} · `note` {title, text} · `caveat` / `thread` {items} · `gallery` · `wikipedia` · `site_embed` · `reddit` `x` `youtube` `instagram` `tiktok` `facebook` `linkedin` `imessage` `whatsapp` (the old site's shapes). ## Two articles that carry each other A house holds `facts.residents: ["person-slug"]` and `![[person-slug|lives here]]` in its body; the person holds `facts.home: "house-slug"` and `{"type":"article","slug":"house-slug","relation":"home"}`. Each card is read live from the other's object: one copy of every fact. Example pair: /a/example-house-14-cypress-lane and /a/example-person-dana-reyes. ## Ontology `above` = broader (the vertical, the parent procedure). `below` = narrower. `adjacent` = beside (same event, alternative path). `nested` = drawn inside this one as cards at the end. Links stay in the JSON; the page shows no link lists unless `show_position: true`. ## House style (the owner's law) - Plain English. Name every thing by what it is. Short sentences. No marketing tone, no filler, no "in today's world". - Data only, never editorial: no scores, rankings, recommendations, advice, pitches or letters. - No invented numbers. A value no source states is the string `"UNKNOWN"`. Every number has a source. - Every fact a reader could check has a source with the exact quote. Run `verify`; publish only when every `quote_found` is true. - Never the site owner's personal name anywhere. - Never call a model through the build to write or test; comments from models are added only when the owner asks for those calls. - Facts live in `facts`; prose explains them. Do not repeat a number in prose that is not in `facts`. ## Done means `GET /a/.json` shows `status: "published"`, every source has `snapshot_sha256` and `quote_found: true`, and `https://miscsubjects.com/a/` answers 200. ## Workbook Tasks and data: build workbook `procedure-verticals` (`GET https://miscsubjects.com/api/wb/procedure-verticals/values?sheet=TASKS` with the key), tabs VERTICALS (BLS QCEW 2024 numbers per vertical), APPLICATIONS (351 procedures, each with its slug), TASKS (70 zero-context tasks), MEASURED VOLUMES, COMPANIES, LIFE EVENTS, PROCEDURE DETAIL, API CALLS. A copy: `/Users/cyrusmassoumi/Downloads/procedure-verticals-2026-10-04.xlsx`. ## Facts ```json { "skill_name": "json-article-writing", "file_on_the_mac": "/Users/cyrusmassoumi/.claude/skills/json-article-writing/SKILL.md", "markdown": "https://miscsubjects.com/a/json-article-writing-skill.md" } ``` --- **above:** [[json-articles-how-they-work]]