docs: progressive complexity guide and feature documentation

[adnaan]

Summary

• Rewrite README "Why" section to highlight the inference → declaration → control gradient
• Replace main example with Tier 1 markdown-native approach (no HTML needed)
• New Progressive Complexity Guide covering all 5 tiers with examples and a decision table
• New Computed Source Reference with configuration, aggregation functions, and behavior docs
• Update auto-rendering, data-sources, and frontmatter reference docs

Test plan

• All markdown links resolve to valid files
• Examples are copy-pasteable
• No code changes — docs only

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds/updates documentation to explain Tinkerdown’s “progressive complexity” approach and to document the new computed source type, while refreshing several reference pages and the README to use more markdown-native examples.

Changes:

• Adds a new Progressive Complexity guide describing tiers 0–4 and how to “graduate” to more explicit UI/rendering approaches.
• Introduces computed source documentation (config, functions, filtering, behavior/limitations) and links it from existing reference pages.
• Updates README and auto-rendering/data-sources/frontmatter docs to reflect the new guidance and source type.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
docs/sources/computed.md	New reference for the computed source type (config, functions, filtering, behavior/limitations).
docs/reference/frontmatter.md	Adds computed to frontmatter source type examples and options.
docs/guides/progressive-complexity.md	New “tiers” guide explaining incremental adoption from markdown to HTML, templates, and WASM.
docs/guides/data-sources.md	Adds computed to the supported source types list.
docs/guides/auto-rendering.md	Clarifies the two auto-rendering modes (inference via markdown tables vs HTML attributes).
README.md	Updates positioning, examples, and source list to include computed + progressive complexity narrative.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

In this frontmatter reference, the source type examples table still uses legacy sqlite fields (path/query) above. The current configuration uses db + table for sqlite, so readers copying from this section will end up with non-working config. Consider updating the sqlite example in the same table while you’re already editing this section to add computed.

[Copilot]

The README now uses db/table for sqlite in the primary example, but later in the same README there’s still a YAML snippet using legacy path/query (and path for JSON) which don’t match the current config keys. For consistency and copy/paste correctness, update the remaining snippets to use db/table (sqlite) and file (json/csv/markdown), etc.

[Copilot]

The README claims “9 data sources out of the box” but the codebase also supports a graphql source type (and the docs include it). Either include GraphQL in the list and update the count, or adjust the wording to avoid an incorrect/fragile count.

Suggested change

	- **9 data sources out of the box.** SQLite, PostgreSQL, REST APIs, JSON, CSV, shell commands, markdown, WASM, and computed/derived sources. Point at existing infrastructure and get a working UI.
	- **10 data sources out of the box.** SQLite, PostgreSQL, REST APIs, GraphQL, JSON, CSV, shell commands, markdown, WASM, and computed/derived sources. Point at existing infrastructure and get a working UI.

[Copilot]

The “9 data sources” feature list omits the graphql source type that’s supported in code and documented elsewhere. Consider including GraphQL here (and updating the count), or removing the numeric count to avoid it getting out of sync as source types evolve.

[Copilot]

The filter operator list includes <= and >=, but the current filter parser regex matches </> before <=/>=, so expressions like points >= 10 will be parsed incorrectly (operator becomes > and value becomes = 10). Either update the docs to omit <=/>= for now, or fix the parser to prioritize <=/>= in the operator match (and add tests for these operators).

Suggested change

	| `<=` | Less than or equal |
	| `>=` | Greater than or equal |

[Copilot]

Auto-refresh currently triggers for write-mutating actions including toggle (in addition to add/update/delete). The behavior description should include toggle or describe this more generally as “write operations” to match runtime behavior.

Suggested change

	- **Auto-refresh:** When the parent source is modified (add, update, delete), all computed sources that depend on it are automatically refreshed.
	- **Auto-refresh:** When the parent source is modified by a write operation (add, update, delete, toggle), all computed sources that depend on it are automatically refreshed.

[Copilot]

The Tier 4 WASM code example uses a plain func Fetch() []map[string]interface{} signature, but the runtime expects specific WASM exports (e.g., fetch, get_result_len, etc.). Update this example to match the actual WASM source interface so it’s copy/pasteable and works with the current loader.

Suggested change

	func Fetch() []map[string]interface{} {
	// Custom data fetching logic
	return []map[string]interface{}{
	{"name": "Custom Item", "value": 42},
	}
	}
	import "encoding/json"
	var result []byte
	//export fetch
	func fetch() {
	// Custom data fetching logic
	data := []map[string]interface{}{
	{"name": "Custom Item", "value": 42},
	}
	// Marshal to JSON so the host can read a single contiguous buffer.
	b, err := json.Marshal(data)
	if err != nil {
	// On error, return an empty JSON array.
	result = []byte("[]")
	return
	}
	result = b
	}
	//export get_result_ptr
	func get_result_ptr() *byte {
	if len(result) == 0 {
	return nil
	}
	return &result[0]
	}
	//export get_result_len
	func get_result_len() int {
	return len(result)
	}
	func main() {}

[Copilot]

This guide still shows legacy sqlite configuration keys (path/query) elsewhere in the file, but the current config struct expects db + table for sqlite sources. Since this PR adds a new source type row, it’s a good opportunity to update the existing sqlite examples on this page to the correct keys (and similarly align other source examples if they use outdated field names).

[claude]

PR Review — docs: progressive complexity guide and feature documentation

Overall this is a well-structured docs-only PR. The new guide is accurate against the implementation and the cross-linking between documents is solid. A few things worth addressing.

Bugs / Inaccuracies

computed.md: != operator description missing case-insensitivity note

The filter operators table documents = as "Equal (case-insensitive)" but != as just "Not equal". Looking at internal/source/computed.go, matchFilter uses strings.EqualFold for both operators — != is also case-insensitive and should say so for consistency.

Suggested fix:

| != | Not equal (case-insensitive) |

docs/reference/frontmatter.md: YAML indentation in table cell may not render correctly

The computed source example in the table uses <br> plus spaces to fake YAML indentation under aggregate:. The two leading spaces inside a <br>-separated table cell will likely collapse in most Markdown renderers, making total: sum(amount) appear at the top level rather than nested. Consider using a code block outside the table, or a simplified single-line form.

Minor Issues

progressive-complexity.md: "Word containment" matching description is slightly loose

The guide says heading "My Monthly Expenses" matches source expenses because it "contains the word". The actual code does word-boundary containment matching against the heading slug (not raw text). This is accurate as shown, but noting that the slug is what's searched would help readers understand why something like "Reexpenses" wouldn't match.

docs/sources/computed.md: filter only supports field-operator-value expressions

The docs correctly show filter: status = active, but don't note that unlike the runtime/interactive filter (which supports bare truthy checks like done or not done), the computed source filter: config field requires the full field operator value form. A one-liner note would prevent confusion.

Verified Correct

• All referenced examples exist: auto-tasks, auto-table-sqlite, auto-table-rest, computed-source
• All cross-linked docs exist: go-templates.md, lvt-attributes.md, wasm.md, auto-rendering.md
• lvt-datatable, auto_bind, lvt-reset-on:success, lvt-confirm are all implemented and referenced accurately
• SQLite table: config option (used in the new README example) is a valid field in config
• The 3-step source matching algorithm (exact → underscore normalization → word containment) matches the code in auto_tables.go
• The 5 aggregation functions (sum, count, avg, min, max) and their nil-skipping behavior are accurately documented
• The "no chaining" computed source limitation matches the startup validation in state.go

---

The != case-insensitivity note and the YAML indentation rendering issue in frontmatter.md are the two things worth fixing before merging. Everything else is cosmetic.

Generated with Claude Code

[claude]

Review: docs: progressive complexity guide and feature documentation

Good overall — the progressive complexity framing is a clear improvement over the previous README, and the computed source docs are well-structured. A few issues worth addressing before merge.

Bug: SQLite config syntax mismatch

The PR introduces a new sqlite shorthand (db: + table:) in the README and progressive-complexity.md:

sources:
  tasks:
    type: sqlite
    db: ./tasks.db
    table: tasks
    readonly: false

But docs/sources/sqlite.md and docs/reference/frontmatter.md consistently use path: + query::

sources:
  tasks:
    type: sqlite
    path: ./tasks.db
    query: SELECT * FROM tasks

If this is a new simplified syntax that was added to the engine, the sqlite source docs need updating too. If it's not yet implemented, the new examples will silently fail. Either way, the docs are now inconsistent — this should be resolved.

TODO comment left in README

<!-- TODO: Add screenshot of rendered auto-table with CRUD controls -->

This should either be resolved before merge or tracked as a follow-up issue and removed from the PR.

Source matching rule 3 is surprisingly broad

The "word containment" matching rule in progressive-complexity.md:

Heading "My Monthly Expenses" matches source expenses

This seems like it could cause unexpected auto-binds in real apps with generic source names like data, items, or list. The docs should note: (a) whether more specific matches take precedence over partial matches, and (b) that auto_bind: false is the escape hatch.

Minor: auto_bind missing from computed.md

The options table in computed.md doesn't list auto_bind, even though frontmatter.md says it applies to all source types. Worth adding a row there for completeness.

Minor: filter syntax could use a quoting note

filter: status = active

It's clear this works as a YAML string, but active looks like it could be a boolean. A brief note (or a quoted example like filter: "status = active") would reduce reader confusion.

---

What looks good:

• All referenced example dirs exist (auto-tasks, auto-table-sqlite, auto-table-rest, computed-source)
• lvt-datatable and lvt-reset-on:success are already documented in existing reference files — consistent with repo conventions
• The decision table at the end of progressive-complexity.md is a nice addition
• Computed source auto-refresh, nil handling, and no-chaining limitations are clearly documented

[claude]

PR Review: Progressive Complexity Guide and Feature Documentation

Overall this is a solid docs addition — the progressive complexity framing is intuitive, and the computed source is well-documented. A few issues to fix before merging.

---

Bugs / Inaccuracies

1. Tier 4 WASM example uses the wrong function signature (blocker)

docs/guides/progressive-complexity.md shows:

func Fetch() []map[string]interface{} {
    return []map[string]interface{}{
        {"name": "Custom Item", "value": 42},
    }
}

But docs/sources/wasm.md documents the actual interface as a low-level memory pointer export:

//export fetch
func fetch(configPtr *byte, configLen int) (dataPtr *byte, dataLen int) { ... }

The simplified signature doesn't compile or work with TinyGo + the Tinkerdown WASM ABI. Either fix the example to match the actual interface, or add a note like "see the WASM source docs for the full interface" without showing pseudocode as real code.

---

2. Unresolved TODO comment in README (blocker)

<!-- TODO: Add screenshot of rendered auto-table with CRUD controls -->

This shouldn't be merged as-is. Either add the screenshot, or remove the comment and do it in a follow-up.

---

3. filter quoting inconsistency in docs/sources/computed.md

The configuration table says:

"status = active" — quote in YAML to avoid parsing issues

But the code examples throughout the file show it unquoted:

filter: status = active  # optional

Pick one convention and apply it consistently. Since the docs themselves recommend quoting, the examples should show quotes.

---

Inconsistency with Existing Docs

4. README and progressive-complexity.md use db: + table: for SQLite, but docs/sources/sqlite.md only documents path: + query:

The new examples use:

type: sqlite
db: ./tasks.db
table: tasks

The canonical sqlite source doc uses:

type: sqlite
path: ./tasks.db
query: SELECT * FROM tasks

The examples directory confirms db: + table: is the current API (see lvt-source-sqlite-test/index.md), so docs/sources/sqlite.md is stale. This PR doesn't need to fix it, but it should not introduce new examples that silently diverge from what the source reference says. Consider adding a note in sqlite.md that the db: + table: shorthand exists, or update the source doc as part of this PR.

---

Missing Information

5. auto_bind: false is only documented in frontmatter.md — not in auto-rendering.md

Since auto_bind controls the auto-table behavior, it belongs in docs/guides/auto-rendering.md under the auto-tables section. A reader discovering auto-tables there won't know about the opt-out mechanism.

6. computed source: no clarification on whether group_by supports multiple fields

The docs show only single-field grouping (group_by: category). Is group_by: [category, status] valid? If not, say so explicitly. If yes, add an example.

---

Minor

• docs/guides/progressive-complexity.md line 94: the slug description for "underscore normalization" is slightly ambiguous — it says slug by-category matches source by_category, but doesn't explain the direction (hyphens → underscores, or both ways). One sentence of clarification would help.
• The decision table at the end is excellent — no changes needed there.

---

What's Working Well

• The 5-tier framing maps cleanly onto the feature set and the "when to graduate" table is genuinely useful.
• Computed source docs are thorough — the nil-handling and deterministic ordering notes in the Behavior section are the kind of detail that saves debugging time.
• lvt-reset-on:success, lvt-confirm, lvt-datatable all correctly match the existing lvt-attributes.md reference — good consistency check.

[claude]

Review

Docs-only PR with solid structure. The progressive complexity framing is clear and the computed source reference is thorough. A few issues to address:

---

lvt-datatable missing from lvt-attributes.md

The Tier 2 example in progressive-complexity.md (and the updated README) use lvt-datatable, which is implemented and documented in auto-rendering.md — but it's absent from docs/reference/lvt-attributes.md. That reference lists all lvt-* attributes and is the canonical source for the attribute surface area. lvt-datatable should be added to the "Tinkerdown-Specific Attributes" section there for consistency.

---

filter: quoting inconsistency (echoing Copilot's finding)

docs/sources/computed.md recommends quoting filter values to avoid YAML parsing issues:

"status = active" — quote in YAML to avoid parsing issues

But the configuration example at the top of the same file shows it unquoted:

filter: status = active  # optional

The progressive-complexity.md examples also show it unquoted. Since status = active happens to parse safely (no colons, special chars), it won't break — but it contradicts the recommendation. Either drop the quoting recommendation or apply it consistently in all examples.

---

SQLite db:/table: vs path:/query: divergence

The PR uses db: + table: throughout (README, progressive-complexity.md, computed.md, computed-source example). The docs/sources/sqlite.md reference only documents path: + query:. Both seem to be valid APIs (the example in lvt-source-sqlite-test uses db: + table:), but a reader following sqlite.md won't know the shorthand exists. Worth adding a note to sqlite.md as part of this PR since the new docs lean on the shorthand heavily.

---

auto_bind: false should appear in auto-rendering.md

It's documented in frontmatter.md but the feature controls auto-table behavior. Readers discovering auto-tables in auto-rendering.md won't find the opt-out mechanism. A short note (or just a cross-reference to frontmatter.md) in the Auto-Tables section would cover this.

---

Minor

• progressive-complexity.md line 94: the underscore normalization description says slug by-category matches source by_category but doesn't state the direction. "Hyphens in slugs are treated as equivalent to underscores in source names" would be unambiguous.
• computed.md: no mention of whether group_by supports multiple fields (e.g., group_by: [category, status]). If it doesn't, say so. If it does, add an example.

---

What's working well

• The tier framing is clean and the "When to Graduate" decision table is genuinely useful.
• The computed source behavior notes (nil handling, deterministic ordering, no chaining) are exactly the kind of detail that prevents debugging surprises.
• All lvt-* attributes used in examples (lvt-reset-on:success, lvt-confirm, lvt-datatable, lvt-actions) are implemented — no phantom attributes.

[claude]

Review: docs: progressive complexity guide and feature documentation

This is a well-written docs PR overall — the progressive complexity framing is clear and the new computed source reference is thorough. A few issues worth fixing before merge.

---

Bug / Inaccuracy

docs/sources/computed.md: filter quoting is inconsistent

The configuration block shows:

filter: status = active  # optional

But the filter field description in the table directly below says:

quote in YAML to avoid parsing issues

These contradict each other. Every filter example in the file uses the unquoted form, but the table warns to quote it. Pick one and apply it consistently — if quoting is needed to avoid YAML misparse, the examples should show it:

filter: "status = active"  # optional

---

CLAUDE.md Compliance

Per project CLAUDE.md: "check if a lvt-* attribute is already implemented in the livetemplate/client repository before reimplementing it"

This PR documents several lvt-* attributes that don't appear in the existing docs/reference/lvt-attributes.md or current docs:

• lvt-reset-on:success (Tier 2 example in progressive-complexity.md)
• lvt-data-id (Tier 3 Go template example)
• lvt-datatable (Tier 2 example, also added to README)

Can you confirm these are already implemented in livetemplate/client? The colon in lvt-reset-on:success is especially worth double-checking — attribute names with colons can cause issues in some HTML parsers and Go's html/template.

---

Minor Issues

README.md: sqlite config key change not called out

The new README example switches the SQLite source from:

path: ./tasks.db
query: SELECT * FROM tasks

to:

db: ./tasks.db
table: tasks

If db: and table: are the current canonical keys, the docs/reference/frontmatter.md source type table still shows the old form (type: sqlite/path:) in the existing entries. Worth updating for consistency, or at minimum adding a note that db: + table: is preferred over path: + query:.

docs/guides/progressive-complexity.md: computed source chaining limitation not mentioned

The Tier 1 section covers computed sources but doesn't mention that a computed source cannot reference another computed source as its parent. Users following the guide naturally try to build up analysis pipelines. A single sentence under "Computed Sources" would prevent a confusing startup error.

---

Looks Good

• Structure and cross-linking between the new and existing docs is solid
• Decision table in the guide is a nice addition
• auto_bind: false escape hatch is well placed
• Filter operator table is clear, especially the numeric vs string distinction

[claude]

PR Review: Progressive Complexity Guide and Feature Documentation

Overall this is a solid docs PR. The progressive complexity framing is well-structured and the examples are consistent with what is in the codebase. A few issues worth addressing before merge.

Issues

1. SQLite API inconsistency (medium)

The PR updates README and the progressive-complexity guide to use the new db:/table: API, but docs/sources/sqlite.md still documents the old path:/query: syntax. This leaves the reference docs contradictory — a user reading the SQLite source docs will get a different API than what the README shows. The sqlite source doc needs updating in this PR.

2. aggregate: missing from frontmatter reference table (minor)

In docs/reference/frontmatter.md, the computed row only shows from: and group_by::

| `computed` | `type: computed`<br>`from: expenses`<br>`group_by: category` |

But aggregate: is required per docs/sources/computed.md. A reader copying this minimal snippet will get a broken config. The example should include at least one aggregate: field.

3. Filter value syntax is underspecified (minor)

The filter syntax uses bare unquoted values (e.g. filter: "status = active") but the docs never clarify what happens with multi-word values or how numeric comparisons work. A note or numeric example (e.g. filter: "amount > 100") would help.

4. Word containment matching could surprise users (minor)

The "My Monthly Expenses" matches expenses example describes a broad heuristic that could catch realistic headings unexpectedly. Consider recommending that source and heading names match closely in Tier 1, and suggest using auto_bind: false proactively on generic source names (e.g. data, items) rather than as a reactive fix.

5. No-chaining constraint not surfaced near from: field (minor)

The constraint that computed sources cannot reference other computed sources is only in the Limitations section at the bottom of computed.md. A brief note near the from: field in the Configuration section would surface it earlier for users designing multi-step aggregations.

Nits

• The README demo image alt text references "expense tracker" while the surrounding code example uses "Task Manager".
• auto_bind in the frontmatter Source Options table should state the default explicitly: "Set to false to exclude from auto-table matching (default: true)".

What is good

• Tier structure maps cleanly to real user needs and the graduation path is well-motivated.
• docs/sources/computed.md is thorough: aggregation functions, filter operators, nil-handling behavior, and deterministic ordering are all specified.
• All referenced examples (auto-tasks, auto-table-sqlite, computed-source, etc.) exist in the repo.
• lvt-datatable and lvt-reset-on:success in the Tier 2 example are already documented in the existing reference docs — no undocumented attributes introduced.

---

Reviewed with Claude Code