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/<slug>), the Markdown (/a/<slug>.md) and the machine copy (/a/<slug>.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).
create (body = the article). 409 if the slug exists
GET /api/jarticles/<slug>
read whole, with hash
PATCH /api/jarticles/<slug> + if-match: <hash>
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/<slug> + if-match
replace whole
GET /api/jarticles/<slug>/at?path=facts.x
one piece + piece_hash
GET /api/jarticles/<slug>/grep?q=<regex>
matches with the path to edit each; GET /api/jarticles/grep?q= across all
POST /api/jarticles/<slug>/verify
fetch every source URL, store snapshot_sha256, quote_found
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"slug": "ca-sr1-accident-report", // /a/<slug>; 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": []
}
Line 14, Column 1JSON
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, 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:<id or n>]] — widgets[n] or the widget with that id
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/<slug>.json shows status: "published", every source has snapshot_sha256 and quote_found: true, and https://miscsubjects.com/a/<slug> 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.
the whole object this page is drawn from, as JSON
{
"schema":"https://miscsubjects.com/schemas/jarticle.json",
"status":"published",
"slug":"json-article-writing-skill",
"title":"The skill for writing JSON articles",
"kind":"skill",
"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"
],
"ontology": {
"above": [
"json-articles-how-they-work"
]
},
"facts": {
"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"
},
"body":"\n# Writing JSON articles for miscsubjects.com\n\nAn article is one JSON object. The site draws the page (`/a/<slug>`), the Markdown (`/a/<slug>.md`) and the machine copy (`/a/<slug>.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).\n\n## Calls\n\nKey: header `x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)`; JSON bodies with `content-type: application/json`. Base: `https://miscsubjects.com`.\n\n| Call | Use |\n| --- | --- |\n| `POST /api/jarticles` | create (body = the article). 409 if the slug exists |\n| `GET /api/jarticles/<slug>` | read whole, with `hash` |\n| `PATCH /api/jarticles/<slug>` + `if-match: <hash>` | 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 |\n| `PUT /api/jarticles/<slug>` + `if-match` | replace whole |\n| `GET /api/jarticles/<slug>/at?path=facts.x` | one piece + `piece_hash` |\n| `GET /api/jarticles/<slug>/grep?q=<regex>` | matches with the path to edit each; `GET /api/jarticles/grep?q=` across all |\n| `POST /api/jarticles/<slug>/verify` | fetch every source URL, store `snapshot_sha256`, `quote_found` |\n| `POST /api/jarticles/<slug>/comments` | `{\"model\":\"<openrouter id>\",\"text\":\"…\"}` |\n| `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 |\n| `GET /api/jarticles/theme`, `PATCH` + `if-match` | the look; every variable listed at `/article-theme.json` |\n| `GET /api/jarticles/models` | the OpenRouter catalog (ids for model/comment widgets) |\n| `GET /schemas/jarticle.json` | the schema |\n\nA 412 means someone changed it after you read it: read again, reapply, resend. Never retry blindly.\n\n## The object\n\n```json\n{\n \"slug\": \"ca-sr1-accident-report\", // /a/<slug>; lowercase, digits, dashes\n \"title\": \"Report a car accident to the California DMV (SR-1)\",\n \"kind\": \"procedure\", // badge: person, house, company, procedure, vertical, model, place…\n \"status\": \"draft\", // \"published\" only after verify passes\n \"summary\": \"One or two sentences. Also the text on this article's card elsewhere.\",\n \"tags\": [\"dmv\", \"california\"],\n \"facts\": { \"authority\": {\"name\": \"California DMV\", \"url\": \"https://www.dmv.ca.gov\"}, \"deadline_days\": 10, \"fee_usd\": 0 },\n \"card_fields\": [\"deadline_days\", \"fee_usd\"], // what a card of this article shows (≤6 paths under facts)\n \"ontology\": { \"above\": [\"vertical-dmv-vehicle-administration\"], \"below\": [], \"adjacent\": [\"ca-vehicle-damage-claim\"], \"nested\": [], \"show_position\": false },\n \"body\": [ \"Markdown…\", {\"type\": \"json\", \"ref\": \"#facts\"}, \"More Markdown…\" ],\n \"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\" } ],\n \"comments\": []\n}\n```\n\nThe build adds `schema`, `created`, `updated`, `version`, `hash`, a source `id` and `quote_sha256` for each source.\n\n## Body\n\n`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:\n\n- `![[slug]]` or `![[slug|relation]]` — that article as a card (Obsidian transclusion)\n- `![[slug#facts.path]]` — one piece of that article as a JSON widget\n- `[[widget:<id or n>]]` — `widgets[n]` or the widget with that `id`\n\n## Widgets\n\n`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).\n\n## Two articles that carry each other\n\nA 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.\n\n## Ontology\n\n`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`.\n\n## House style (the owner's law)\n\n- Plain English. Name every thing by what it is. Short sentences. No marketing tone, no filler, no \"in today's world\".\n- Data only, never editorial: no scores, rankings, recommendations, advice, pitches or letters.\n- No invented numbers. A value no source states is the string `\"UNKNOWN\"`. Every number has a source.\n- Every fact a reader could check has a source with the exact quote. Run `verify`; publish only when every `quote_found` is true.\n- Never the site owner's personal name anywhere.\n- Never call a model through the build to write or test; comments from models are added only when the owner asks for those calls.\n- Facts live in `facts`; prose explains them. Do not repeat a number in prose that is not in `facts`.\n\n## Done means\n\n`GET /a/<slug>.json` shows `status: \"published\"`, every source has `snapshot_sha256` and `quote_found: true`, and `https://miscsubjects.com/a/<slug>` answers 200.\n\n## Workbook\n\nTasks 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`.\n",
"created":"2026-10-05T01:35:59.639Z",
"updated":"2026-10-05T01:35:59.639Z",
"version":1,
"hash":"9df1ee647a2991e5ceced6fcc7a264446a077fd0ee42d1b4d1c9dfa545f68cfb",
"styling": {
"scope":"shared",
"how":"no value on the page is set by hand: each comes from this theme, and each theme value becomes the CSS variable named beside it. PATCH https://miscsubjects.com/api/jarticles/theme changes them.",
"widget_style": {
"what":"every widget may carry style: {…}; these are the only keys it reads",
"rotate":"degrees, a number",
"offset_x":"pixels, a number",
"offset_y":"pixels, a number",
"pulse":"true to pulse"
},
"theme": {
"color": {
"page_bg":"#f5f5f7",
"sheet_bg":"#ffffff",
"ink":"#1d1d1f",
"soft":"#424245",
"muted":"#6e6e73",
"dim":"#86868b",
"line":"#d2d2d7",
"accent":"#0071e3",
"accent_soft":"rgba(0,113,227,0.08)",
"link":"#0066cc",
"selection":"rgba(0,113,227,0.18)",
"widget_bg":"#f5f5f7",
"widget_border":"#d2d2d7",
"card_bg":"#ffffff",
"code_bg":"#f5f5f7",
"json_bg":"#161b19",
"json_ink":"#e6e1d4",
"json_key":"#7fd3c3",
"json_string":"#e9c46a",
"json_number":"#f4a261",
"json_bool":"#c792ea",
"json_null":"#928d7e",
"json_punct":"#6b6759",
"json_bar":"#0e1512",
"kind_badge_bg":"#0e6e60",
"kind_badge_ink":"#ffffff"
},
"color_dark": {
"page_bg":"#000000",
"sheet_bg":"#1d1d1f",
"ink":"#f5f5f7",
"soft":"#d2d2d7",
"muted":"#a1a1a6",
"dim":"#86868b",
"line":"#424245",
"accent":"#2997ff",
"accent_soft":"rgba(41,151,255,0.12)",
"link":"#2997ff",
"selection":"rgba(41,151,255,0.25)",
"widget_bg":"#2c2c2e",
"widget_border":"#424245",
"card_bg":"#1d1d1f",
"code_bg":"#2c2c2e",
"json_bg":"#0a0d0c",
"json_ink":"#e6e1d4",
"json_key":"#7fd3c3",
"json_string":"#e9c46a",
"json_number":"#f4a261",
"json_bool":"#c792ea",
"json_null":"#757062",
"json_punct":"#5d665f",
"json_bar":"#060807",
"kind_badge_bg":"#4fc1ab",
"kind_badge_ink":"#0b0f0d"
},
"font": {
"display":"-apple-system,BlinkMacSystemFont,\"SF Pro Display\",\"SF Pro Text\",\"Helvetica Neue\",Helvetica,Arial,sans-serif",
"body":"-apple-system,BlinkMacSystemFont,\"SF Pro Display\",\"SF Pro Text\",\"Helvetica Neue\",Helvetica,Arial,sans-serif",
"mono":"ui-monospace,SFMono-Regular,\"SF Mono\",Menlo,Consolas,monospace",
"google_fonts":""
},
"size": {
"body":"17px",
"small":"17px",
"eye":"17px",
"lead":"17px",
"h1":"52px",
"h2":"34px",
"h3":"22px",
"byline":"17px",
"h1_measure":"none",
"code":"17px",
"json":"17px",
"widget_title":"17px"
},
"leading": {
"body":"1.7",
"head":"1.18",
"lead":"1.5",
"json":"1.6"
},
"weight": {
"display":"700",
"head":"700",
"body":"400",
"strong":"700",
"eye":"700"
},
"tracking": {
"eye":"0.14em",
"display":"-0.03em",
"body":"-0.006em",
"badge":"0.08em"
},
"layout": {
"sheet_width":"1000px",
"text_width":"880px",
"gutter":"16px",
"sheet_padding":"56px 64px 64px",
"sheet_padding_mobile":"24px 18px 40px",
"sheet_margin":"28px auto 72px",
"block_gap":"1.15em",
"widget_gap":"28px",
"grid_gap":"14px"
},
"border": {
"sheet":"0px solid",
"sheet_radius":"30px",
"widget":"1px solid",
"widget_radius":"24px",
"card_radius":"24px",
"badge_radius":"999px",
"rule":"1px solid",
"code_radius":"18px",
"accent_bar":"3px"
},
"shadow": {
"sheet":"0 1px 1px rgba(0,0,0,.02),0 6px 26px rgba(0,0,0,.05)",
"widget":"none",
"card_hover":"0 10px 28px -16px rgba(28,27,23,0.35)"
},
"motion": {
"hover":"160ms ease"
}
}
},
"page":"https://miscsubjects.com/a/json-article-writing-skill",
"json":"https://miscsubjects.com/a/json-article-writing-skill.json",
"markdown":"https://miscsubjects.com/a/json-article-writing-skill.md",
"theme":"https://miscsubjects.com/article-theme.json",
"calls": [
{
"what":"this article as a page (no key)",
"method":"GET",
"url":"https://miscsubjects.com/a/json-article-writing-skill",
"headers": {}
},
{
"what":"this article as its object (no key)",
"method":"GET",
"url":"https://miscsubjects.com/a/json-article-writing-skill.json",
"headers": {}
},
{
"what":"this article as Markdown (no key)",
"method":"GET",
"url":"https://miscsubjects.com/a/json-article-writing-skill.md",
"headers": {}
},
{
"what":"the object with its hash, drafts too",
"method":"GET",
"url":"https://miscsubjects.com/api/jarticles/json-article-writing-skill",
"headers": {
"x-sheets-key":"$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
}
},
{
"what":"one piece and that piece’s hash",
"method":"GET",
"url":"https://miscsubjects.com/api/jarticles/json-article-writing-skill/at?path=facts",
"headers": {
"x-sheets-key":"$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
}
},
{
"what":"grep: every key or value that matches, with the path to change it",
"method":"GET",
"url":"https://miscsubjects.com/api/jarticles/json-article-writing-skill/grep?q=owner",
"headers": {
"x-sheets-key":"$(cat /Users/cyrusmassoumi/.misc-sheets-key)"
}
},
{
"what":"change pieces (set, merge, delete, append, insert, move); if-match is the hash",
"method":"PATCH",
"url":"https://miscsubjects.com/api/jarticles/json-article-writing-skill",
"headers": {
"x-sheets-key":"$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
"content-type":"application/json",
"if-match":"<hash from the read>"
},
"body": {
"ops": [
{
"op":"set",
"path":"facts.example",
"value":1
}
]
}
},
{
"what":"replace the whole object",
"method":"PUT",
"url":"https://miscsubjects.com/api/jarticles/json-article-writing-skill",
"headers": {
"x-sheets-key":"$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
"content-type":"application/json",
"if-match":"<hash>"
},
"body": {
"slug":"json-article-writing-skill",
"title":"…"
}
},
{
"what":"fetch every source, hash what came back and check the quote is in it",
"method":"POST",
"url":"https://miscsubjects.com/api/jarticles/json-article-writing-skill/verify",
"headers": {
"x-sheets-key":"$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
"content-type":"application/json"
},
"body": {}
},
{
"what":"an Obsidian-style command",
"method":"POST",
"url":"https://miscsubjects.com/api/jarticles/cli",
"headers": {
"x-sheets-key":"$(cat /Users/cyrusmassoumi/.misc-sheets-key)",
"content-type":"application/json"
},
"body": {
"command":"backlinks",
"file":"json-article-writing-skill"
}
}
]
}