---
name: jsony
description: >-
  Keep the JSON backbone aligned after `apps/` commits: `flove-fields`,
  `routing.json`, `APP_ROUTING` and the export envelopes. Queues findings;
  never edits canonical files unasked. Use for /jsony.
category: sys
checker_of:
  - https://flove.org/development/standards/json.md
  - https://flove.org/development/wiki/INDEX.md

---

# jsony — the JSON backbone checker

Shared JSON files connecting apps, routing, Appy and the export envelopes.
Not a replacement for `exporty`: **exporty audits one app's export surface**;
**jsony checks the shared backbone** and says which app needs aligning.

## The backbone

| File | Role | Owner |
|---|---|---|
| `tools/routing.json` | canonical registry: id, name, category, URL, field tree, cross links, consumers | canonical; update after review |
| `tools/puzzy.json` | showcase lexicon (`words{}`) only | hand-authored; routing is the canonical registry |
| `apps/appy/index.html` | Appy import/export + `APP_ROUTING` offline snapshot | checked; snapshot follows routing |
| `apps/**/*.html` `flove-fields` | each app's embedded field manifest | app source |
| `development/wiki/work/common.json` | page-facing join: hito specs + live tasks + archive summary (`flove-common/1`) | generated by `build-common.py`; never hand-edited |
| `development/index.html` `work-data` | embedded Work fallback: `archive` + `queuePolicy` | generated by `build-work-tracker.py`; jsony checks it too |
| Work export inbox + shared projection | `work-moves.json` · `register_projection.py` | jsony blocks unapplied moves; generators share the projection |
| app `flove-portrait/1` / Appy `flove-profile` | the extractive export envelopes | app + Appy |

**Decision (skills-03.2a, 2026-11-21, owner):** `critical` rows block; no new edge.

## The routine

**When a commit touches `apps/`**, the post-commit hook only **queues** changed
files: it never runs the checker, blocks the commit or edits canonical files.
Processing is opt-in, scheduled or manual.

```bash
ln -sf ../../tools/dev/jsony-post-commit .git/hooks/post-commit
chmod +x tools/dev/jsony-post-commit
```

The hook runs `jsony_check.py --record --soft`, appending changed files to
`tools/jsony-state.json` (`lastCommit`, `lastRun`, `queue[]`) — a watermark.

```bash
python3 tools/dev/jsony_check.py --changed --soft  # process the queue
python3 tools/dev/jsony_check.py                   # full check
python3 tools/dev/jsony_check.py --strict          # CI / final, fails on drift
python3 tools/dev/jsony_check.py --app goddy        # one app's export audit
python3 tools/dev/jsony_check.py --summary         # summary-standard worklist (CSS-narrowed apps count as compliant)
python3 tools/dev/build-common.py --check          # common.json vs milestones.json
python3 tools/dev/check-restore.py
python3 tools/dev/build-work-tracker.py --apply-moves
```

`--changed` writes the pending report, records the commit in `lastCommit` and
clears the queue; remove the hook with `rm .git/hooks/post-commit`.

Outputs: `tools/jsony-pending.{md,json}` (human review, proposed entries, apply order;
JSON twin for a later tool pass), `tools/jsony-state.json` (queue + watermark).

## Per-app export audit

`--app <id|name>` resolves the app through `tools/routing.json` and checks its
file against the export standard — Goddy is the reference model: portrait API,
`flove-portrait/1`, `<app>-portrait.json`, `phrase`, `rows[]`, no legacy
serializers or Publish bridge, `canShare` around `navigator.share`. Missing
API/schema/filename are critical; the rest is advisory. A page in
`EXPORT_EXCEPTIONS` is reported as a documented exception and not audited —
`exporty` owns those apps' surfaces.

Summaries follow [`frontend/summary.md`](https://flove.org/development/standards/frontend/summary.md) — the Goddy model: **Magic · Share**, with
Save as Share's first option (JSON), never a separate Save button.

`--summary` also enforces the two-button shape: an app whose markup still has a
standalone Save, or no Magic/Share pair, is reported until it is converted.

`--app` is static: it greps the file and cannot prove the export runs. The
runtime twin is `development/tools/conformance.html` — one dev page that loads
each app in an iframe and calls `window.flovePortrait.conformance()`: validate,
row integrity, blob name/MIME, probe-row merge. It is a smoke test, not a
replacement for `exporty` (renderer and real round-trip stay there). The inline
block is generated: `python3 tools/dev/inject-conformance.py --check` reports drift,
`--apply` rewrites it. Do not hand-edit the block inside an app.

### Exceptions — one set, variants in the docs

`jsony_check.py` carries a single `EXPORT_EXCEPTIONS` set; the code holds no
variants and no second list. The variants — an app that keeps its own HTML
export, an app without the standard summary, a page outside the export
contract — are documented only in [`frontend/export.md`](https://flove.org/development/standards/frontend/export.md) (§ Exceptions and
§ Pages outside the export contract) and [`frontend/summary.md`](https://flove.org/development/standards/frontend/summary.md) (§ Exceptions).
Each page's type is in the development index's app table:
`development/index.html` → **Web → Apps** (`#web-apps`). To change an exception,
edit those docs first, then the set.

## What it checks

| Check | Severity |
|---|---|
| app `flove-fields` id exists in `routing.json` | critical |
| every `routing.json` app URL resolves on disk | critical |
| `APP_ROUTING` has every routing id with the same category | critical |
| `APP_ROUTING` has no extra ids | critical |
| appy-basic still exports `flove-profile`, `flove-routing/3`, `appsPlayed`, `flove-portrait/1`, `flovePort` | critical |
| apps with fields have a `flovePortrait` / `flovePort` envelope | advisory |
| the inlined Publish bridge copies across apps agree | advisory |

CSS-pure apps are not flagged for a missing export — that call is `exporty`'s.
The bridge comparison never fails a build: it groups the embedded copies by
variant and lists them in the pending report; copying one variant into the others
is a routine cleanup, not a gate.

### Retired — the puzzy registry snapshot

EXP08 closed 2026-11-21: `tools/puzzy.json` keeps only the hand-authored
`words{}` lexicon, driven by `tools/dev/build-puzzy-demo.py`.
The `apps{}` snapshot and parked `tools/pending/` sync were removed;
`tools/routing.json` is the single canonical registry.

## Apply order

1. Read `tools/jsony-pending.{md,json}`; decide each critical item.
2. After any `milestones.json` change, run
   `python3 tools/dev/build-common.py --build` so the page join lists
   all live tasks (1,455) and archived tasks (805).
3. Add or fix the `routing.json` entry. For field trees run
   `python3 tools/extract-fields.py --apply`.
4. Update the `APP_ROUTING` snapshot in `apps/appy/index.html` (`id` +
   `category` only; colours stay Appy's own).
5. Run `exporty` on the changed app(s) to align the per-app export surface.
6. Re-run `jsony_check.py --strict` until clean; delete the pending files.

## Boundaries

- **No silent edits.** The routine writes pendings; canonical files change after
  review or an explicit `--apply`.
- **No app UI changes** — the backbone and the Appy snapshot, not app markup.
- **No secrets** in routing URLs.
- **Exporty alignment** after any routing/Appy change: same ids, same categories.
- **Reverse handoff:** when an `exporty` repair changes an app's `flove-fields`,
  its `flove-profile` / `flove-portrait/1` envelope or its `floveStore` keys, run
  `jsony_check.py --strict` — an envelope change is backbone drift too.
- **New categories are an owner decision** — the pending entry says
  `category: "TODO"` rather than guessing.

Standing rules: `https://flove.org/development/standards/skills/standing.md`.
