{ "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/`), 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).\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/` | read whole, with `hash` |\n| `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 |\n| `PUT /api/jarticles/` + `if-match` | replace whole |\n| `GET /api/jarticles//at?path=facts.x` | one piece + `piece_hash` |\n| `GET /api/jarticles//grep?q=` | matches with the path to edit each; `GET /api/jarticles/grep?q=` across all |\n| `POST /api/jarticles//verify` | fetch every source URL, store `snapshot_sha256`, `quote_found` |\n| `POST /api/jarticles//comments` | `{\"model\":\"\",\"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/; 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:]]` — `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/.json` shows `status: \"published\"`, every source has `snapshot_sha256` and `quote_found: true`, and `https://miscsubjects.com/a/` 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": "" }, "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": "" }, "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" } } ] }