Cluster detail
site/reqs
Ideas located under folder site/reqs.
folder
63 ideas
4 files
| Idea | File | Status | Summary |
|---|---|---|---|
| assets | site/reqs/core.rq | this site is published in in gh pages at the " / reqlan " path. Any assets in the / public folder should be referenced as " / reqlan / assets /... ". Embedded spec export hrefs follow the same base via [spec_html_export] / [html_export.html_export_url_base]. | |
| brand | site/reqs/core.rq | must be aligned with ["../../reqlan rq/brand.rq"] | |
| code_block_styling | site/reqs/core.rq | Code blocks should be styled per language as a function of a classname; or by using an appropriate lightweight external dependency. . rq,. ts,. md, and. py should be supported for code sections. If using a dependency, it should parse at build, not in the browser. | |
| components | site/reqs/core.rq | - sidebar - footer - hero - sticky page nav graph ( landing ) - links / contact - showcases - tutorials per [tutorials_section] - content - motivation - syntax - example - CTA: - download the extension per [icon_reqs.cta_icon] - 404 page ( just something silly / a redirect ) | |
| copy | site/reqs/core.rq | - In a ts object decoupled from the actual layout / styling. - copy should be really super minimal and concise if at all. ( show don't tell ) | |
| images | site/reqs/core.rq | The source logo is in the / public folder. A sharp dev script is used to generate pngs and favicons etc which should be executed if the svg source logo changes. | |
| links | site/reqs/core.rq | per [phonebook_reqs.phonebook] per [phonebook_reqs.npm_packages] Contact shows phonebook `links` then a Packages subsection for phonebook `packages`. per [icon_reqs.link_icons] per [icon_reqs.package_icons] | |
| logo | site/reqs/core.rq | - there is a logo in the sidebar. | |
| pnpm | site/reqs/core.rq | Must use pnpm for all js package management. | |
| presentation_player_route | site/reqs/core.rq | done | `/presentations/player/` is a statically exported Next page that loads runtime deck JSON from `/presentations/decks/` and Reveal from `/presentations/vendor/reveal.js/`. Runtime JSON is generated from authored JSONC by [sync_presentations]. It must not use SiteShell; it is iframe-hosted by tutorial detail pages. Do not place `public/presentations/player/index.html` — that path is owned by the App Router export. |
| simple_lightweight_and_static | site/reqs/core.rq | must be fully statically exported for GitHub Pages. All routes, including showcase detail pages, are generated at build time. The deploy workflow must upload only static HTML, JS, and assets from site / out. Build also embeds the workspace requirement graph under `/spec` per [spec_html_export]. | |
| single_page | site/reqs/core.rq | just one page. | |
| site | site/reqs/core.rq | the / site folder contains a static Next. js App Router landing page for reqlan. | |
| spec_html_export | site/reqs/core.rq | done | The site static build exports the workspace requirement graph ( excluding `*.secret.rq` ) under `out/spec/` via `reqlan export`. It must pass [html_export.html_export_url_base] for `/spec` ( honouring `SITE_BASE_PATH`, e. g. `/reqlan/spec` in production ) so `/spec` loads with or without a trailing slash. It must pass [html_export.html_export_header_link] pointing at the marketing site home so readers can leave the embedded spec and return to the parent site. Pipeline: ["../scripts/build-static.mts"] → ["../scripts/export-spec.mts"] → ["../scripts/verify-static-export.mts"]. Host options come from [html_export.html_export] / CLI [cli_package.commands]. |
| sync_presentations | site/reqs/core.rq | done | `scripts/sync-presentations.mts` reads authored `*.jsonc` decks and `manifest.jsonc`, emits comment-free `*.json` for the static player, and syncs assets / vendor into `public/presentations/`. |
| tutorial_location_crumb | site/reqs/core.rq | done | Tutorial detail chrome shows a compact location trail: catalog → course → lesson → slide. Hierarchy must be obvious without a wide single-line title dump. Layout: each tier is a stacked chip — role ( and optional completion control ) on the top row; title / index value muted underneath. Titles colour up on hover, focus-within, or when the peer menu is open. * * Folder navigation: * * each tier acts like a path segment / folder. Hover or focus reveals a peer menu for that level of the tree so the user can jump without using the transport row: - catalog → courses ( enter first lesson of the chosen course, or the catalog index ) - course → peer courses - lesson → peer lessons in the active course - slide → peer slides in the active lesson ( updates the embedded player / `?slide=` ) Current peer is marked; menus stay keyboard-reachable via focus-within. * * Sizing: * * the crumb container grows to fit text; wrap before truncating. Ellipsis only as a last resort on very narrow viewports — do not cap chip width so aggressively that titles ellipsize while space remains. Course deep-links also exist at `/tutorials/#course-<series>`; catalog at `/tutorials/`. Slide shows `n/total` and updates live with the embedded player. Completion toggles stay on the role row. The crumb lesson tier always shows the * * current * * lesson only — it must not share hover / preview state with the transport lesson step dots. Step-dot hover may preview a title near the dots, never in the crumb. |
| tutorials_section | site/reqs/core.rq | done | The site exposes `/tutorials` and `/tutorials/[slug]/` as statically generated pages. Catalog and deck ids come from authored ["../../presentations/manifest.jsonc"]. Each detail page embeds the Reveal player iframe at `/presentations/player/?deck=<id>` using [assets] / SITE_BASE_PATH-aware `sitePath`. Each detail page hosts a unified transport chrome ( `<<` `<` steps `>` `>>` ) that drives slide nav in the embedded player via postMessage, plus lesson jumps. Location hierarchy chrome: [tutorial_location_crumb]. Blurb and try-this live on the catalog and inside the slides, not as page chrome. The player is an App Router page ( [presentation_player_route] ) so it static-exports under `trailingSlash` without colliding with `public/` HTML. Sync ( [sync_presentations] ) converts authored deck / catalog JSONC under ["../../presentations/"] into runtime JSON under `public/presentations/`, and copies assets plus vendored Reveal. js ( player shell excluded ). |
| workflow | site/reqs/core.rq | Site deployment runs when an `site/v*` tag is pushed. Tags are created automatically on main by the release workflow per [distribution_reqs.deployment_flow]. The site workflow does not deploy on ordinary commits. per [distribution_reqs.site_distribution] | |
| cta_icon | site/reqs/icons.rq | The hero install control is a single " Install " menu button that opens an editor / download chooser ( Cursor, VS Code, Open VSX, Download VSIX ) — it must not assume the user's editor or pre-select one silently. Each menu row shows the target's icon beside its full label; icons resolve through [phonebook_icon_registry] via the quickstart icon set / name refs in ["../src/content/install-actions.ts"]. per ["./core.rq".components] | |
| current_link_icons | site/reqs/icons.rq | Slugs are defined on each link in ["../../reqlan rq/phonebook.json"]: - `site` → mdi / web - `vsc` → simple-icons / visualstudiocode - `openvsx` → simple-icons / vscodium ( proxy; no Open VSX slug in Simple Icons ) - `github` → simple-icons / github - `email` → mdi / email-outline Package entries under `packages` all use simple-icons / npm: - `language`, `analytical`, `cli` | |
| icon_registry | site/reqs/icons.rq | [phonebook_icon_registry] maps phonebook icon keys to bundled Iconify data. Every link and package icon in the phonebook must have a matching registry entry; the module throws at startup if one is missing. When adding or changing an icon in ["../../reqlan rq/phonebook.json"], update the registry import for that slug. | |
| iconify_stack | site/reqs/icons.rq | The site renders icons with Iconify offline — bundled at build time, not fetched from a CDN at runtime. Renderer: `@iconify/react` via [phonebook_icon_component]. Icon data: npm packages listed under the `icons` key in ["../../reqlan rq/phonebook.json"] per [phonebook_reqs.phonebook_icons]. Icons must remain compatible with static export per ["./core.rq".simple_lightweight_and_static]. | |
| link_icons | site/reqs/icons.rq | The contact link row in [contact_component] renders an icon beside each phonebook link label. per ["./core.rq".links] | |
| package_icons | site/reqs/icons.rq | The contact Packages row in [contact_component] renders an icon beside each phonebook package label. Package entries come from ["../../reqlan rq/phonebook.json"]. packages per [phonebook_reqs.npm_packages]. per ["./core.rq".links] | |
| phonebook_icon_component | site/reqs/icons.rq | [phonebook_icon_component] is the single render entry point for phonebook icons. It accepts a phonebook `icon` ref and renders an inline SVG with `aria-hidden`. Default sizing uses the `.phonebook-icon` class in ["../src/styles/globals.css"]. | |
| phonebook_icon_keys | site/reqs/icons.rq | per [phonebook_reqs.phonebook_icons] Each phonebook link or package carries an `icon` object with `set` and `name`. Set ids and lookup URLs are canonical in ["../../reqlan rq/phonebook.json"]. icons. Use each set's `search` URL to find replacement slugs when a name changes or an icon is removed upstream. Typed helpers live in [phonebook_script]: `formatPhonebookIconKey`, `getPhonebookIconSearchUrl`. | |
| scope | site/reqs/icons.rq | site icon rendering for phonebook links and CTAs | |
| absorbed_and_dropped | site/reqs/showcase.rq | 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. | |
| agent_context_showcase | site/reqs/showcase.rq | done | 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. |
| antipatterns_showcase | site/reqs/showcase.rq | done | 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. |
| attribute_dialect_showcase | site/reqs/showcase.rq | done | 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. |
| audit_trail_showcase | site/reqs/showcase.rq | done | 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. |
| broken_links_showcase | site/reqs/showcase.rq | done | 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. |
| diagrams_are_never_dressed_as_code | site/reqs/showcase.rq | ASCII arrow diagrams must not sit inside language- " rq " blocks. They get their own visually distinct block kind. aligns with [showcase_module] | |
| every_rq_block_must_parse | site/reqs/showcase.rq | 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 | site/reqs/showcase.rq | A diagnostic, a query response, a coverage report, or a graph. If there is no tooling output, it is not a showcase. | |
| features_not_demonstrated | site/reqs/showcase.rq | 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. | |
| features_tier_1 | site/reqs/showcase.rq | The reasons to adopt. All verified as shipping today. | |
| features_tier_2 | site/reqs/showcase.rq | The depth. Also shipping. | |
| firmware_cloud_contract_showcase | site/reqs/showcase.rq | done | 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. |
| graph_view_showcase | site/reqs/showcase.rq | done | 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]. |
| interlock_showcase | site/reqs/showcase.rq | done | 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. |
| legacy_archaeology_showcase | site/reqs/showcase.rq | done | 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. |
| module_surface_showcase | site/reqs/showcase.rq | done | 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. |
| one_worked_example_per_page | site/reqs/showcase.rq | 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. | |
| phase_0_honesty_audit | site/reqs/showcase.rq | pending | In parallel with content rewrite. Fix what the honesty audit surfaced. |
| phase_1_parse_gate | site/reqs/showcase.rq | 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 | site/reqs/showcase.rq | 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 | site/reqs/showcase.rq | 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 | site/reqs/showcase.rq | 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 | site/reqs/showcase.rq | done | Detail page layout: beats with captions, mechanism badges distinct from tags, and cross-block highlighting of the shared identifier. |
| phase_6_capture_media | site/reqs/showcase.rq | done | Capture real media from the extension for [broken_links_showcase] ( diagnostics / quick-fix ) and [graph_view_showcase] ( Cytoscape ). |
| showcase | site/reqs/showcase.rq | done | 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_languages | site/reqs/showcase.rq | . 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] | |
| showcase_module | site/reqs/showcase.rq | 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_plan | site/reqs/showcase.rq | Ideaset (showcase_plan) | |
| showcase_problems | site/reqs/showcase.rq | 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. | |
| showcase_rules | site/reqs/showcase.rq | 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 | site/reqs/showcase.rq | Ideaset (showcase_rules_set) | |
| showcase_set | site/reqs/showcase.rq | Ideaset (showcase_set) | |
| showcase_thesis | site/reqs/showcase.rq | 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. | |
| test_proves_showcase | site/reqs/showcase.rq | done | 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. |
| styling_architecture | site/reqs/styling.rq | styling should be handled primarily at the compoenent level with co-located css module files that are imported in the react components. |
Initialising graph…