spec - showcase.rq

Ideas 35

References 116

Statuses 3

Tags 39

Idea	Status	Tags	Summary
showcase	done	site, showcase, content	Every showcase demonstrates a mechanism, not a metaphor. Domain problem, the. rq that binds it, the real artifact in another language it binds to, and the thing the tooling hands back. Content is authored in TS objects per [showcase_module], not generated from this file at runtime. This file is the source of truth for intent, ordering, and editorial rules.
showcase_thesis			Current showcases demonstrate the syntax, not the toolset. A reader who finishes them thinks: you can write sentences in curly brackets. Nothing shows what you get back — no query and answer, no diagnostic, no graph, no round trip. The upgrade thesis: every showcase demonstrates one mechanism against a real domain problem. Code in, artifact out. No showcase ships without a payoff block.
showcase_problems			Three concrete failures of the current set: Invalid reqlan. Samples use illegal attribute forms ( colon-list tags, pipe-scalar plans, nested reference objects ) that do not parse against the langium grammar. For a language project, shipping invalid samples on the marketing site is an own-goal. Prose dressed as semantics. A file ref followed by the word " implements " and an idea ref reads like a typed relation, but " implements " is body text. Reqlan has five edge kinds ( references, file_reference, ideaset_member, import, comment_link ) and none are user-declared. We imply a feature that does not exist while hiding the ones that do. Vapor features. Graph showcase tells people to run Reqlan: Export JSON, which is not registered. The docs-attribute page is built around an attribute with no special tooling.
every_rq_block_must_parse			Every language- " rq " block in showcases. ts must parse against the langium grammar. Prefer enforcement via a build step that runs the real parser over content. aligns with [phase_1_parse_gate]
every_showcase_ends_in_a_payoff			A diagnostic, a query response, a coverage report, or a graph. If there is no tooling output, it is not a showcase.
one_worked_example_per_page			Consistent identifiers across every block on a page. The reader should trace one name from requirement to source to test to search result without re-orienting.
diagrams_are_never_dressed_as_code			ASCII arrow diagrams must not sit inside language- " rq " blocks. They get their own visually distinct block kind. aligns with [showcase_module]
showcase_rules		editorial, rules	Four editorial rules. Enforced in content and, where possible, at build time. See [every_rq_block_must_parse], [every_showcase_ends_in_a_payoff], [one_worked_example_per_page], [diagrams_are_never_dressed_as_code].
showcase_rules_set			Ideaset (showcase_rules_set)
features_tier_1		features, tier-1	The reasons to adopt. All verified as shipping today.
features_tier_2		features, tier-2	The depth. Also shipping.
features_not_demonstrated			Deliberately not demonstrated — they do not exist yet. Typed relation kinds, reference wildcards, hover cards, autoformatting, JSON / CSV export palette commands, PDF binary, vector-embedding search. Keyword-scored search must not be marketed as semantic search / embeddings.
agent_context_showcase	done	ai, mcp, planning	Flagship. Context for the agent, not the repo. An agent answers a question about session expiry. Show the repo-dump cost, then MCP file_context returning six ideas and their edges, then the plan the agent writes. Absorbs former agentic-planning and feature-tracking pages.
interlock_showcase	done	industrial, safety, sequencing	Flagship. The interlock that must not fail. A safety requirement bound to ["./plc/interlock.stL#41-58"] by symbol and line range, to a vitest case by test name, with an rq-comment in the ST source pointing back. Domain: industrial control / IEC 61131.
broken_links_showcase	done	diagnostics, refactor	Flagship. Links that break loudly. Someone renames a file. Show the diagnostic, the quick-fix menu, and the rewritten refs. This is the argument against a wiki. Domain: refactor safety, any stack.
firmware_cloud_contract_showcase	done	integration, cross-stack, embedded	Flagship. The contract between firmware and cloud. A 10 Hz sample rate and a 50 ms ingest deadline: one invariant, two codebases, neither of which can express it alone. Absorbs half of former glue-semantics and static-connection.
audit_trail_showcase	done	compliance, audit, export	Depth. An audit trail you can export. Custom clause / evidence / verified_by attributes, then Completion Status showing the coverage gap, then HTML export as the auditor's deliverable. Domain: regulated software — IEC 62304 or SOC 2. Absorbs former compliance page.
module_surface_showcase	done	modularity, imports, ideasets	Depth. A module's published surface. billing / interface. rq exports an ideaset; checkout. rq imports only that; reaching past the boundary is an unresolved-import error. Ideasets-as-public-API is undemonstrated today. Absorbs half of former glue-semantics and module-interface.
test_proves_showcase	done	testing, traceability	Depth. What this test actually proves. Keep the intent of the former test-explanation page; upgrade it with a real test-name anchor and the reverse direction from test file back to intent.
legacy_archaeology_showcase	done	legacy, discovery, deprecation	Depth. Archaeology on inherited code. An undocumented function, an rq-comment seeded into it, @ deprecated on the old path, then Deprecation Impact listing everything that breaks. Absorbs former scattered-docs page.
graph_view_showcase	done	extension, graph	Depth. See the whole graph. Needs real captured screenshots or a short loop from the actual Cytoscape view — not fake ASCII arrows dressed as. rq. Aligns with [diagrams_are_never_dressed_as_code].
attribute_dialect_showcase	done	attributes, extensibility	Depth. Attributes as a domain dialect. The full attribute grammar: flags, negated flags, block values, nested and named lists — forms nobody currently knows about. Absorbs former arbitrary-attributes page.
antipatterns_showcase	done	antipattern, craft	Depth. Three ways to write. rq badly. Data instead of pointers, prose restating code, one monolithic file. Showing negative space is a taste signal. Absorbs former data-not-ideas page; expands it.
showcase_set			Ideaset (showcase_set)
absorbed_and_dropped			Absorbed into the eleven: glue-semantics splits into [firmware_cloud_contract_showcase] and [module_surface_showcase]. agentic-planning and feature-tracking fold into [agent_context_showcase]. compliance becomes [audit_trail_showcase]. scattered-docs becomes [legacy_archaeology_showcase]. test-explanation upgrades into [test_proves_showcase]. arbitrary-attributes upgrades into [attribute_dialect_showcase]. static-connection upgrades into [firmware_cloud_contract_showcase]. data-not-ideas expands into [antipatterns_showcase]. graph-traversal upgrades into [graph_view_showcase]. control-system-sequencing upgrades into [interlock_showcase]. module-interface upgrades into [module_surface_showcase]. Dropped: todo-triage — too thin; triage is a byproduct of [agent_context_showcase], not a page. docs-attribute — sells tooling that does not exist; file refs to markdown belong inside other pages.
showcase_module	done		Showcases are standardised and typed in TS content objects. Short version ( list card ): id, title, summary, tags, mechanism badge. Long version ( detail page ): full blocks array including payoff. Exist as a list page and as a full page per slug. Routes: / showcase / and / showcase / [slug] / — static export. Block kinds needed beyond today's code \| features union: callout — the one-sentence point of the page exchange — query + response, terminal-styled diagnostic — editor-style error with quick-fixes diagram — visually distinct from code; never language- " rq " caption / mechanism fields on the showcase object Copy stays minimal and show-don ' t-tell, aligned with site copy rules.
showcase_languages			. rq blocks use the custom site tokenizer. Non-. rq blocks need Shiki coverage beyond today's ts / md / py — add st, c, json, yaml for the flagship domains. aligns with [phase_1_parse_gate]
phase_0_honesty_audit	pending	tooling, honesty	In parallel with content rewrite. Fix what the honesty audit surfaced.
phase_1_parse_gate	done		Make dishonesty impossible. Add a build step that runs the Langium parser over every language- " rq " block in showcases. ts and fails on parse errors or unresolved local refs. Do this first so the rewrite cannot reintroduce the current problem. Also expand Shiki language set per [showcase_languages].
phase_2_content_schema	done		Extend ShowcaseBlock union and Showcase type per [showcase_module]. Presentation polish can follow in [phase_5_detail_layout]; schema first.
phase_3_reqs_as_truth	done		This file is the source of truth: one idea per showcase with mechanism, domain, and status; [showcase_set] listing them; refs into showcases. ts. Reqlan's own showcase plan is tracked in reqlan.
phase_4_write_the_eleven	done		Write the eleven, one at a time, each validated by [phase_1_parse_gate] before moving on. Flagships first — [agent_context_showcase], [interlock_showcase], [broken_links_showcase], [firmware_cloud_contract_showcase] — so the format can be judged before committing to all eleven.
phase_5_detail_layout	done		Detail page layout: beats with captions, mechanism badges distinct from tags, and cross-block highlighting of the shared identifier.
phase_6_capture_media	done		Capture real media from the extension for [broken_links_showcase] ( diagnostics / quick-fix ) and [graph_view_showcase] ( Cytoscape ).
showcase_plan			Ideaset (showcase_plan)