From a3880be117f9ec94ac4abcba6aa02066c685deee Mon Sep 17 00:00:00 2001 From: Adnaan Badr Date: Fri, 24 Jul 2026 22:53:58 +0000 Subject: [PATCH] docs: refresh README for the ephemeral-UI reframe + stamp CHANGELOG v0.4.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README already led with the reframe narrative (M0 Phase 1), but had gone stale on the concrete machinery M1–M5 actually shipped. Bring it up to date, and cut the CHANGELOG for the v0.4.0 release. README: - Governed-generation model: rewrite "AI-Assisted Development" → "Generating apps under policy" — the /tinkerdown skill's approved-surface flow (the generation: block), enforced-twice (validate at generation + runtime), on-brand design tokens + style_guide, /tinkerdown:save + the gallery, and the pii-access-approval console as the worked example (the app reads via read-only sources; every write goes through a governed, audited action). Drops the plan's aspirational consent gate — no such flag shipped. - Flagship "Governed approval console" row in What You Can Build. - Fix source count 9 → 10 and add the missing GraphQL row (real source, has an example) — reconciles the table + Key Features with the prose that already listed GraphQL. - Tier-4 WASM: note writable sources (export `write`) + serve/cli parity. - Version banner v0.2.x → v0.4.x. - Fix two broken ROADMAP.md links (the file moved to docs/archive/): drop the Planning link, point Contributing at the open issues. CHANGELOG: - Stamp the reframe [Unreleased] block as [v0.4.0] - 2026-07-24 (all of it merged after v0.3.9), and open a fresh empty [Unreleased]. The v0.3.x releases were tagged but never CHANGELOG'd; that pre-existing gap is left as-is rather than backfilled. Gate: non-E2E full suite green (17 pkgs ok, 0 fail); build clean. The Docker-Chrome E2E suite was not run — the diff is two markdown files with no runtime surface (nothing served, parsed, or loaded by any app), and no test pins the repo-root README content. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_018M9pJSPmG6i1D8s6rpEV4h --- CHANGELOG.md | 7 +++++++ README.md | 36 ++++++++++++++++++++---------------- 2 files changed, 27 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a7339ddc..6e994a97 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,13 @@ Earlier releases (v0.1.x) are documented in the ## [Unreleased] +## [v0.4.0] - 2026-07-24 + +The ephemeral-UI reframe (M0–M5): Tinkerdown becomes the tool teams use to let an +LLM generate contextual, throwaway internal UIs against an **approved surface** — +governed at generation *and* runtime, on-brand by construction, saveable when a +workflow recurs. Everything below shipped since v0.3.9. + ### Fixed — `tinkerdown cli` reaches WASM sources; wasm docs use the real config keys `tinkerdown cli` now constructs `wasm` sources, so a WASM source has the same CRUD diff --git a/README.md b/README.md index be5b9e52..190d7f46 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Tinkerdown -> **v0.2.x — early but tagged. Expect breaking changes between minors.** +> **v0.4.x — early but tagged. Expect breaking changes between minors.** **Internal UIs cheap enough to throw away. Describe what you need, get a live app against your real data, delete it when you're done.** @@ -82,6 +82,7 @@ The same primitive scales to other artifacts: | Artifact | What it looks like | |---|---| +| **Governed approval console** | A request queue where **Approve** runs a bounded, audited export and **Deny** records a decision — generated against an *approved surface*, not freeform. ([examples/pii-access-approval](examples/pii-access-approval)) | | **Dashboard / status report** | Frontmatter pulls from PostgreSQL or REST; tables, computed totals, and Mermaid diagrams render inline. ([examples/markdown-data-dashboard](examples/markdown-data-dashboard)) | | **Literate doc / runnable explainer** | Prose alongside live widgets, real source cited by line range, and your deployed app embedded inline — the doc *is* the working code. ([Literate Authoring guide](docs/guides/literate-docs.md), [examples/literate-counter-include](examples/literate-counter-include)) | | **Triage / standup board** | Action buttons mutate a shared SQLite or PostgreSQL source; every teammate's tab stays in sync over WebSocket. ([examples/standup-bot](examples/standup-bot), [examples/team-tasks](examples/team-tasks)) | @@ -125,14 +126,14 @@ See the [Literate Authoring guide](docs/guides/literate-docs.md) for the full pr {{end}} ``` ```` -- **Tier 4 — WASM sources.** Write a custom data source in TinyGo when built-ins don't fit; the module exports a `fetch` function and runs server-side. +- **Tier 4 — WASM sources.** Write a custom data source in TinyGo when built-ins don't fit; the module exports a `fetch` function — and, for a writable source, a `write` — and runs server-side, with the same behavior under `tinkerdown serve` and `tinkerdown cli`. See the [Progressive Complexity Guide](docs/guides/progressive-complexity.md) for full examples and the escape hatches between tiers. ## Key Features - **Single-file apps**: Everything in one markdown file with frontmatter -- **9 data sources**: SQLite, JSON, CSV, REST APIs, PostgreSQL, exec scripts, markdown, WASM, computed +- **10 data sources**: SQLite, PostgreSQL, REST, GraphQL, JSON, CSV, exec scripts, markdown, WASM, computed - **Auto-rendering**: Tables, selects, and lists generated from data - **Real-time updates**: WebSocket-powered reactivity - **Zero config**: `tinkerdown serve` just works @@ -166,6 +167,7 @@ sources: | `json` | JSON files | [lvt-source-file-test](examples/lvt-source-file-test) | | `csv` | CSV files | [lvt-source-file-test](examples/lvt-source-file-test) | | `rest` | REST APIs | [lvt-source-rest-test](examples/lvt-source-rest-test) | +| `graphql` | GraphQL APIs | [lvt-source-graphql-test](examples/lvt-source-graphql-test) | | `pg` | PostgreSQL | [lvt-source-pg-test](examples/lvt-source-pg-test) | | `exec` | Shell commands | [lvt-source-exec-test](examples/lvt-source-exec-test) | | `markdown` | Markdown files | [markdown-data-todo](examples/markdown-data-todo) | @@ -238,21 +240,26 @@ sources: See [Configuration Reference](docs/reference/config.md) for when to use each approach. -## AI-Assisted Development +## Generating apps under policy -Tinkerdown's surface area is small on purpose: a fixed `lvt-*` attribute vocabulary, frontmatter with a small set of well-defined fields, and a single file that contains the whole app. That gives an LLM very few ways to be wrong. +Tinkerdown's surface area is small on purpose — a fixed `lvt-*` vocabulary, a handful of frontmatter fields, and one file that *is* the whole app — so an LLM has very few ways to be wrong. The `/tinkerdown` skill turns that into a workflow: describe what you need, and the agent authors the markdown, runs `tinkerdown validate` against the real parser, self-corrects on the line-numbered diagnostics until it's clean, then serves it. -Describe what you want, and the agent drafts the markdown: +What makes it safe to point an LLM at real data is the **approved surface**. A `tinkerdown.yaml` declares a `generation:` block naming exactly which sources and actions an agent may wire up — everything else is off-limits: -``` -Create a task manager with SQLite storage, -a table showing tasks with title/status/due date, -a form to add tasks, and delete buttons on each row. +```yaml +generation: + sources: [access_requests, audit_log, datasets] # the only sources a generated app may bind + actions: [request-access, approve-export, deny-request] # the only actions it may invoke + style_guide: ./style-guide.md # house conventions the agent follows ``` -The output is a `.md` file you can read, diff, and hand-edit. No component tree, no build config, no `node_modules` to reason about. +- **Declared once, enforced twice.** An agent may only use approved names — an unapproved name fails `validate` before anything serves — and the same surface is enforced again at **runtime**: a running app, a webhook, or a crafted message can only invoke an approved action or write an approved source, so a caller bypassing the browser can't reach past what you approved. Projects with no `generation:` block are unaffected — approval is opt-in. +- **On-brand by construction.** House style is data, not a prompt. `styling.tokens` maps design tokens (`accent`, `card_bg`, …) to your palette and skins the semantic HTML the generator emits; `generation.style_guide` points at a markdown file of conventions the skill reads and follows. Generated UIs match the house style without careful prompting. +- **Keep it if it recurs.** Generated UIs are ephemeral by default. When one is worth keeping, `/tinkerdown:save` captures the working app — manifest, fixtures, and house style — into a re-runnable skill that stands up again in seconds with no regeneration, listed in a discoverable [gallery](examples/gallery). -See [AI Generation Guide](docs/guides/ai-generation.md) for tips on Claude Code, Cursor, and other agents. +**Worked example — an access-approval console.** [`examples/pii-access-approval`](examples/pii-access-approval) is a request queue generated against the approved surface above. The app *reads* through read-only sources; every *write* goes through a governed, audited action. **Approve** runs a bounded, server-authoritative export — the row cap comes from the request row, not the client — and appends a durable audit record in a single transaction; **Deny** records a decision without granting access. The manifest is the record of what the console is allowed to do. + +The output of all of this is a `.md` file you can read, diff, and hand-edit — no component tree, no build config, no `node_modules`. See the [AI Generation Guide](docs/guides/ai-generation.md) for using it with Claude Code, Cursor, and other agents. ## Documentation @@ -275,9 +282,6 @@ See [AI Generation Guide](docs/guides/ai-generation.md) for tips on Claude Code, - [Configuration (tinkerdown.yaml)](docs/reference/config.md) - [lvt-* Attributes](docs/reference/lvt-attributes.md) -**Planning:** -- [Roadmap](ROADMAP.md) - ## Development ```bash @@ -294,7 +298,7 @@ MIT ## Contributing -Contributions welcome! See [ROADMAP.md](ROADMAP.md) for planned features and current priorities. +Contributions welcome! Browse the [open issues](https://github.com/livetemplate/tinkerdown/issues) for where help is wanted. ## Acknowledgements