spec

python_file_reference

example_rq_project/a source folder/a reqfile.rq

A reqlan comment should be able to reference a python file apythonfile.py

python_line_reference

example_rq_project/a source folder/a reqfile.rq

A reqlan comment should be able to reference a python file line or line range apythonfile.pyL#1-2

python_symbol_reference

example_rq_project/a source folder/a reqfile.rq

A reqlan comment should be able to reference a python file symbol say_hello

hello

example_rq_project/an idea in a folder/another idea.rq

this is another idea in a folder.

myimportableIdea

example_rq_project/exampleimport.rq

this is an importable idea.

myimportableIdea

example_rq_project/exampleimport1.rq

this is an importable idea.

myimportableIdea

example_rq_project/exampleimport2.rq

this is an importable idea from exampleimport2. rq.

myidea

example_rq_project/main.rq

It should be a good thing.

my_unbracketed_one_liner_idea

example_rq_project/main.rq

ideas should support one liners

my_second_idea

example_rq_project/main.rq

this is a blob of text

my idea2

example_rq_project/main.rq

it should be compatible with myidea. myidea which are also supported.

Status: pending

Tags: todo, highpriority

my_ideaset

example_rq_project/main.rq

Ideaset (my_ideaset)

a_simple_idea

example_rq_project/main.rq

doesn't require a block , if it is just a blob than it can be written on a single line without braces .

myidea3

example_rq_project/sub idea.rq

application must have something. this should align with myidea and also with myimportableIdea

Tags: style, accessibility, performance

spec

packages/extension/src/analytical_submodule/spec.rq

this folder is the extension host adapter for `@reqlan/analytical` : VS Code wiring ( watchers , Uri helpers , export UI , command registration ) over the shared WorkspaceIndex engine . Index ownership lives in packages / analytical .

welcome

packages/extension/templates/thanks-for-installing.template.rq

Thank you for installing the reqlan toolset.
This page introduces the extension, the reqlan language, and where to learn more.

resources

packages/extension/templates/thanks-for-installing.template.rq

- Project site: { { SITE_URL } }
- Documentation and quickstart: { { QUICKSTART_URL } }
- Source repository: { { GITHUB_URL } }
- Visual Studio Marketplace: { { VSC_URL } }
- Open VSX Registry: { { OPENVSX_URL } }

extension_overview

packages/extension/templates/thanks-for-installing.template.rq

The reqlan extension provides language support for `.rq` requirement files in VS Code and compatible editors.
Use the Reqlan activity bar to inspect neighbourhood context, reference lists, and graph slices for the active requirement.
In chat, invoke `@reqlan` with `/rq-search` to explore requirements across the workspace.

language_overview

packages/extension/templates/thanks-for-installing.template.rq

Requirements are expressed as named ideas with prose, attributes, and cross-references.
Ideas may use block `{... }` syntax or concise one-line declarations.
Reference related ideas with wiki links and bracket notation, and link to implementation with file references such as `login`.
Syntax reference and examples are available at { { SITE_URL } }.

acknowledgements

packages/extension/templates/thanks-for-installing.template.rq

- LLMs
- PKMs

skills

reqlan rq/ai-support.rq

rq- * skills ( chat_skill_naming, cursor_skills_install ) teach the graph, not the whole repo.
Ontology in one breath — this project as example:
- idea — named unit of intent ( `cli_package`, `skills` )
- file / ideaset — containers ( `reqlan rq/cli/cli_package.rq`; file = implicit ideaset )
- base — `.reqlan` boundary; one ideas index per base
- reference — `idea` / `wiki` / `idea` to ideas and code
- attribute / attribute_body — `@name …`; first unmarked text is the body
Prefer focused search / file context / local graph over full dumps ( ai_integration ).

Status: done

special_attributes

reqlan rq/ai-support.rq

When creating or updating ideas, skills MUST set:
- `@status` — lifecycle ( `draft` | `pending` | `in-progress` | `done` | … )
- `@todo` — open gaps / follow-ups ( bare or with a note )
- `@tests` — quoted test paths that prove the idea ( optional `:test name` suffix )
Do not bury status, todos, or test links in body prose.

Status: done

cli

reqlan rq/ai-support.rq

Headless twin of extension / MCP analysis: cli_package ( `reqlan` / `rq` ), same `<base>/.reqlan` index.
commands: `init` · `parse <file>` · `analyse` / `analyze` · `search <query>` · `export` / `export html`.
`--json` for machines; `--cwd` / `REQLAN_WORKSPACE`; `REQLAN_INDEX_PATH` overrides index dir.

Status: done

base

reqlan rq/bases/base.rq

A base is a container for ideas, ideasets, and files.
It forms the boundary of one ideas graph and is consumed by the CLI and the extension.
Marker: a directory is a base only when it owns a `.reqlan` folder ( application_memory ).
No bare workspace folder is treated as a base until the user creates `.reqlan` there
( create_base_onboarding ).
Aligns with ontology_base.
Discovery and registry: base-discovery.ts, base-registry.ts.
Marker path helpers: application-memory.ts.

base_ownership

reqlan rq/bases/base.rq

Each base holds its own ideas_index store under `<base>/.reqlan/ideas-index.sqlite`.
Path keys inside the index are relative to that base root, not the VS Code workspace root.
Store path: application-memory.ts; per-base engine: workspace-index.ts via base-registry.ts.

base_configuration

reqlan rq/bases/base.rq

Base configuration is distinct from, but related to, configuration.rq.
Optional settings live at `<base>/.reqlan/config.json` ( one config per base ).
For an `.rq` file, the applying base is the nearest ancestor that owns `.reqlan`; that base's config applies when present.
See configuration_location; resolved by reqlan-path-resolve.ts.

base_configuration_provider

reqlan rq/bases/base.rq

Base-level settings live at `<base>/.reqlan/config.json`.
Extension-level settings remain VS Code configuration for the product host.

base_nesting

reqlan rq/bases/base.rq

Bases may nest: any subdirectory that owns its own `.reqlan` is a child base.
Parent-base indexing includes only `.rq` files under the parent root that are * * not * * under
any child base root ( base-discovery.ts ownership exclusion ).
Nested bases appear as siblings in the multi-base registry; the longest-matching base root
wins for a given file path ( implied_context ).

base_linking

reqlan rq/bases/base.rq

A base may have one-directional relationships with other bases.
This follows a subscription model.
Bases may be cross subscribed.
Unless linked, than bases remain isolated.
Base linking is configured in the config file in the base. reqlan directory.
- an unlinked child base should sever the contained ideas from the parent base ( i. e. the parent should just see the child as a separate base and child ideas shouldn't be visible, the indexer shouldn't crawl it. ) they should be functionally distinct
- bases, distinct from eachother in the system file tree, should be linkeable ( either one way or both ways )
- A linked child base should allow the parent base to see the child's ideas. The indexs should be linked, and the child counts etc should be included in the parents.
- A child base should always be able to link to parent base ideas.

base_modes

reqlan rq/bases/base.rq

A base may be linked to

base_initialisation

reqlan rq/bases/base.rq

Bases are initialised with `<base>/.reqlan/config.json`, `.reqlan/.rqignore` ( gitignore-syntax path filters; see configuration_rqignore ), and a sqlite ideas index under `.reqlan`.
create-base.ts creates the `.reqlan` marker and seeds a minimal `config.json` plus default `.rqignore` when the base is new.
Full install sequencing ( extension welcome vs base seeds vs agent files ): base_installation.

implied_context

reqlan rq/bases/base.rq

The * * active base * * for editor-adjacent surfaces is the longest-matching base root that
contains the focused file path. When no file is focused, the last selected base ( Ideas Summary
switcher / activity bar ) or the first discovered base is used.
Context, local graph, and analysers bind to the active base's index — not a merged global graph.
User / explicit pin is a pointer swap only — active_base_switch.
Core selection: base-discovery.ts ( `baseForPath` / `selectDefaultBase` ); editor pin / switch: index-service.ts.

active_base_switch

reqlan rq/bases/base.rq

Changing the active base is a * * pointer swap * * onto a per-base `WorkspaceIndex` / store.
- Do * * not * * await soft-sync, hard-rebuild, or a full `.rq` walk on the switch call itself.
- Host surfaces rebind views to the newly active store ( status snapshot, tables, context panes ) immediately.
- If the selected base is not yet ready, show its readiness / progress and * * schedule * * the normal activate catch-up
( open if needed, then one soft sync ) fire-and-forget — same path as triggers /
indexing_trigger_open, not a special switcher rebuild.
- Idle staleness checks also heal unopened / never-synced bases ( they cannot mtime-diff without a store ).
- `activateAll` isolates open failures so one bad base cannot leave siblings stranded in `uninitialized`.
- Editor-follow must not overwrite a user pin on the same refresh that applies the selection.
Surfaces: activity bar workspace_base_picker, Ideas Summary ideas_summary_base_scope.
Implemented by index-service.ts ( `setActiveBaseId` / `scheduleBaseCatchUp` ); engine: base-registry.ts `ensureBaseReady`, workspace-index.ts `ensureReady`.

Status: done

multi_base_environment

reqlan rq/bases/base.rq

Analytical features are multibase aware via base-registry.ts:
one ideas_index / `WorkspaceIndex` per base, isolated catalogs ( no cross-base idea-id collision ).
Surfaces list all discovered bases; Ideas Summary and context panes scope to the active / selected base ( active_base_switch ).
Cross-base reference resolution and merged graphs are out of scope for the first multi-base pass.
Headless ( CLI / MCP ) selects one base via create-runtime.ts; the editor hosts index-service.ts.

create_base_onboarding

reqlan rq/bases/base.rq

When discovery finds * * zero * * bases under any VS Code workspace folder ( root or child ),
the extension prompts the user to create a reqlan base at the workspace-folder root.
Do not auto-create `.reqlan`. Command `reqlan.createBase` creates `<folder>/.reqlan/`
( empty directory is a valid marker ), rediscovers, and activates indexing for that base.
With multiple workspace folders and no bases, prompt against the first folder.
Headless create-base helper: create-base.ts ( also used by CLI `init` ).

brand

reqlan rq/brand.rq

reqlan has a simple brand . Dark rust ; and aqua blue pallete . Pink for highlights . Logo is nodular graph / crosshair

extension_brand

reqlan rq/brand.rq

The extension uses the brand logo from logo.svg.
PNG is used for marketplace, language file icon, activity bar, README, and chat participant surfaces ( Azure Marketplace rejects SVG ).
WebP is generated as a raster fallback.

file_icon

reqlan rq/brand.rq

the file icon for. rq files should use the reqlan logo.

cli_package

reqlan rq/cli/cli_package.rq

`packages/cli` ( `@reqlan/cli` ) is the Clipanion CLI published to npm as the `reqlan` ( and `rq` ) binary.
It depends on `@reqlan/analytical` for base analysis and `@reqlan/language` for single-file parse.
Entry: main.ts.
Analysis commands reuse application_memory ( `<base>/.reqlan` ) and the analytical index so the CLI shares the ideas index with the extension and MCP.

architecture

reqlan rq/cli/cli_package.rq

The cli should be a thin wrapper around the analytical and language packages.

commands

reqlan rq/cli/cli_package.rq

Minimal commands:
- `parse <file>` — parse one `.rq` file via `@reqlan/language`; print diagnostics or an AST summary ( `--json` for machine output ).
- `analyse` / `analyze` — file ( `--file` ), idea ( `--idea` ), or workspace completion ( default ) via `AnalysisApi`.
- `search <query>` — semantic search via `AnalysisApi.searchRequirements`.
- `export` / `export html` — multi-file HTML site via `AnalysisApi.exportHtml` ( html_export ).
`--exclude-secret` omits `*.secret.rq`.
`--exclude-ignored` omits paths matched by `.reqlan/.rqignore`.
`--url-base` mounts root-relative hrefs per html_export_url_base.
`--header-href` / `--header-label` set the topbar home link per html_export_header_link.
- `init directory` — create a new base marker ( `.reqlan` ) at the given path or cwd ( init ).

watch

reqlan rq/cli/cli_package.rq

The cli should be able to watch a base and maintain the index as files change.

init

reqlan rq/cli/cli_package.rq

The cli should be able to initialise a new base.
Creates `<path>/.reqlan/` ( empty directory is a valid marker ), matching create_base_onboarding.
Headless helper lives in `@reqlan/analytical` so CLI and extension share one create-base path.

Status: done

function_parity

reqlan rq/cli/cli_package.rq

CLI shares headless function definitions with MCP and other tools through `@reqlan/analytical` `AnalysisApi`, not VS Code host APIs from extension.
On-disk index storage follows application_memory ( same `.reqlan` path as the extension ); optional override via `REQLAN_INDEX_PATH`.

Status: done

mission_statement

reqlan rq/constitution.rq

This project offers a structred semantic framework for supporting people working with llms to document their semantic requirements as code ; and provide ergonomic consumption and definition of them .

llm_first

reqlan rq/constitution.rq

The language should be designed to be easy to use with llms.
It should be support token minimisation.

vsc_first

reqlan rq/constitution.rq

The language should be designed to be easy to use with vscode .

general_purpose

reqlan rq/constitution.rq

The language should work in any stack . And ideally , even in non-software development environments .

simplicity

reqlan rq/constitution.rq

The language should be simple to understand and use , and offer flexibility in the syntax for minimised friction and bp .

scope

reqlan rq/constitution.rq

The scope of these requirments spans the entire project , including the language itself , the developer-user tooling , and the reqlan-developer environment .

inspiration

reqlan rq/constitution.rq

This project draws upon ideas from the following fields:
- LLMS
- Software development
- Obsidian / Personal Knowledge Management systems.
- Industrial Control Engineering
- Ontology based business information systems

supply_chain

reqlan rq/constitution.rq

The supply chain for this project should be open and transparent, minimising risk and immature dependencies.

scope

reqlan rq/core-architecture.rq

These requirements describe the cross-package system architecture of the reqlan monorepo:
language definition, language server, ideas index, editor product, and companion tools.
They are distinct from scope, which bounds only the VS Code extension and LSP product surface.
Language concepts live in ontology.rq; syntax truth lives in syntax.rq; editor module contracts live under extension / module.
Grouped as workspace_packages, language_runtime, and product_map.

monorepo

reqlan rq/core-architecture.rq

The workspace is a pnpm monorepo ( `packages\*`, extension webviews, and `site` ) per pnpm-workspace.yaml.
TypeScript project references build in order language → analytical → mcp → cli → extension per tsconfig.build.json.
Living requirements for the product live in this `reqlan rq` folder.
Root orchestration ( Langium generate, package builds, Cursor skill sync ) lives in package.json.
Why libraries are separate packages ( and how Changesets sees them ): package_versioning.

language_package

reqlan rq/core-architecture.rq

`packages/language` ( `@reqlan/language` ) is the canonical language definition.
It owns Langium grammars, generated AST and parser, scoped linking, validators, and LSP service providers.
Public DI entry is reqlan-module.ts via `createReqlanServices`.
Consumers: analytical_package ( indexer / analysis ), extension_package ( LSP ), cli_package.
Published to npm as a library dependency of language_package and language_package; not Marketplace-published. See version_management and package_versioning.

analytical_package

reqlan rq/core-architecture.rq

`packages/analytical` ( `@reqlan/analytical` ) is the shared requirement graph index and analysis layer.
It owns the indexer.rq: extracts ideas and edges from Langium ASTs into a sql. js SQLite store ( workspace-index.ts ), holds Zustand analytical state, and exposes analysers and an analysis API.
Headless entry is create-runtime.ts via `createAnalysisRuntime` / `WorkspaceIndex`.
Consumers: extension_package ( thin editor adapter ), mcp_package, cli_package.
Depends on language_package. Published to npm alongside analytical_package; version graph role: package_versioning.

extension_package

reqlan rq/core-architecture.rq

`packages/extension` ( npm `reqlan-extension` ) is the editor product per extension_package.
It registers `.rq` language support, TextMate grammars, starts the language client, and owns activity bar, Ideas Summary, chat, skills, and mutation hooks.
Ideas index engine lives in analytical_package / indexer.rq; the extension only hosts a thin VS Code adapter ( index-service.ts ) for watchers and UI.
Host entry: main.ts. LSP process entry: main.ts.
Depends on language_package and extension_package.
Follows event_driven and state_machine_mindset ( zustand ) for JS state.
This is the one Marketplace / Open VSX shippable; see package_versioning.

mcp_package

reqlan rq/core-architecture.rq

`packages/mcp` ( `reqlan-mcp` ) is a stdio MCP server over the analytical analysis API — no VS Code host required.
Entry: main.ts. Used by Cursor and other MCP clients per mcp and mcp_tools.
Ignored by Changesets and `private` ( not an npm publishable ) per version_management.

cli_package

reqlan rq/core-architecture.rq

`packages/cli` ( `@reqlan/cli` ) is a Clipanion CLI over language_package ( parse ) and analytical_package ( `AnalysisApi` for analyse / search ).
Entry: main.ts. Binary name `reqlan` ( alias `rq` ). Published to npm with language and analytical per package_versioning and version_management.

site_package

reqlan rq/core-architecture.rq

`site` is the marketing / docs Next. js site per site_package.
It is off the language-service and ideas-index path.
Release-driving publishable alongside extension_package; see package_versioning.

package_versioning

reqlan rq/core-architecture.rq

Separate workspace packages exist for build isolation and reuse — not because each ships to every channel.
language_package and analytical_package are leaf libraries shared by LSP, index, MCP, and CLI; they need their own package boundaries for TypeScript project refs and a single grammar / index ownership point.
Release-driving channels:
- Marketplace / Open VSX: extension_package ( `ext/v*` )
- GitHub Pages: site_package ( `site/v*` )
- npm registry: package_versioning, package_versioning, and cli_package ( `language/v*`, `analytical/v*`, `cli/v*` ) via Changesets `changeset publish`
Changesets config is config.json. It ignores mcp_package only.
language_package and analytical_package stay in the Changesets graph so a lib change can bump their versions and patch dependents via `updateInternalDependencies: "patch"` ( including the extension and CLI ).
Extension webview folders may be private pnpm members ( e. g. `@reqlan/ideas-summary-webview` ) so Vite / Svelte can own deps; they bundle into extension media and are not Changesets publish targets. Activity-bar UI is not a separate package. json product.
Contributors record release intent with a changeset on publishable packages when user-facing behaviour changes; see version_management.

grammar_and_parser

reqlan rq/core-architecture.rq

Grammar is Langium ( Chevrotain ), not tree-sitter.
Main `.rq` grammar: reqlan.langium. Comment-token grammar for `rq:…` in non- `.rq` sources: reqlan-comment.langium.
`langium generate` produces AST / grammar modules and TextMate JSON; TextMate is patched and copied into the extension at build time per build_prepare.
Syntax requirements that the grammar must satisfy live in syntax.rq; conceptual units in idea, ideaset, reference, import_statement.
Services are wired in reqlan-module.ts.

language_server

reqlan rq/core-architecture.rq

The language server is a separate Node process started by the extension host over IPC ( main.ts → main.ts ).
It runs reqlan-module.ts `createReqlanServices` for live editing: definition, completion, semantic tokens, inlays, document links, validation.
It owns open-document language intelligence for `.rq` files ( and related language features ), not the full-workspace SQLite ideas index.
Product expectation for LSP navigation and validation: lsp_support.

ideas_index

reqlan rq/core-architecture.rq

The ideas index is built and maintained by the indexer.rq in analytical_package.
Path: parse with language_package → extract ideas / edges → SQLite via workspace-index.ts.
Application memory: each base holds SQLite under `<base>/.reqlan/` ( shared by extension, cli_package, and mcp_package ) — see application_memory.
Multi-base: a BaseRegistry owns one workspace-index.ts per discovered base; the extension adapter routes file events to the owning base.
In the editor, index-service.ts watches `**\*.rq` and forwards changes to the owning base's workspace-index.ts; it serves UIs, commands, chat, and analysers.
Headless ( MCP / CLI ) uses create-runtime.ts ( nearest base containing cwd when several exist ).
Capability requirements: index_ideas, index_technology, and sibling analysers in that file.
Triggers: triggers and idea_index_triggers.

base_containers

reqlan rq/core-architecture.rq

Ideas are organised in base.rq; each base holds the ideas_index store under its `.reqlan` application memory.
Discovery and nesting: base, base_nesting.

runtime_topology

reqlan rq/core-architecture.rq

Two Langium runtimes share language_package but not one process.
- LSP process: live `.rq` editing intelligence via main.ts.
- Analytical workspace-index.ts ( extension host via index-service.ts, MCP / CLI via create-runtime.ts ): full-workspace graph for tables, local graph, chat, MCP.
Editor ↔ extension host: VS Code APIs and webview postMessage.
Editor ↔ LSP: vscode-languageclient IPC.
Attribute catalog and similar custom notifications may sync from the index side into the LSP for completions.
Stack sketch: stack.

extension_surfaces

reqlan rq/core-architecture.rq

Product surfaces on extension_package are specified in module / feature docs, not here:
- Activity bar sidebar: activity_bar
- Composed context model ( any workspace file ): context_scope
- Context scope v2 ( signals, synthesis, show-don ' t-tell widgets ): context_scope_v2
- Webview surfaces ( shared discipline + catalog ): webview
- Ideas Summary tables / graph webview: ideas_summary
- Chat participant `@reqlan` and MCP wrap: chat_participant, features-skills-and-mcp.rq
- Create / split / merge / rename mutation hooks: features-mutation-hooks.rq
- Analysers and index behaviour: features-graph-analysers.rq

hierarchy_of_truth

reqlan rq/core-architecture.rq

Align with hierarchy_of_requirements:
- User request trumps these requirements; these requirements trump current implementation.
- Language concepts: ontology.rq; syntax rules: syntax.rq.
- Package seams and process topology: this file ( workspace_packages, language_runtime ).
- Editor UI and host contracts: extension / module and features- * files ( product_map ).
- Distribution and publishables: distribution.rq; internal vs shippable versioning: package_versioning.

workspace_packages

reqlan rq/core-architecture.rq

Ideaset (workspace_packages)

language_runtime

reqlan rq/core-architecture.rq

Ideaset (language_runtime)

product_map

reqlan rq/core-architecture.rq

Ideaset (product_map)

scope

reqlan rq/development/build.rq

extension build steps for local development and CI

extension_build

reqlan rq/development/build.rq

Production builds for the VS Code extension are orchestrated by build.mjs.
Run from the extension package: `pnpm run build` or `node scripts/build.mjs`.
Workspace-wide builds also run langium generation and sibling packages via the root `pnpm run build`.
Local and F5 builds use incremental_extension_build; VSIX prepublish uses the forced path.

incremental_extension_build

reqlan rq/development/build.rq

Extension builds fingerprint inputs and outputs per independently cacheable artifact:
- Langium generated sources / TextMate grammar
- generated shared graph-physics source
- logo media
- generated marketplace README
- each of the five Vite webviews separately
- extension-host / language-server / lazy sql. js esbuild outputs
A step is skipped only when its command / input fingerprint and current output-content fingerprint both match the cache under `packages/extension/out/`.
Missing, changed, or manually edited output invalidates that step.
Webview output fingerprints cover each complete emitted directory, including future lazy chunks. Host-bundle inputs include bundled phonebook data and the sql. js vendor source as well as workspace package output.
TypeScript retains its native `tsc -b` project-reference incrementality.
TextMate syntax copies are cached by content; Cursor-skill sync still runs because it targets workspace-external state.
`pnpm run build:force` / `node scripts/build.mjs --force` bypasses all cache entries; `vscode:prepublish` uses this forced mode for release correctness.
`clean` removes `out/`, including the cache, so clean builds remain cold.
Root `pnpm run build:ext` delegates only to the extension package. The extension build generates Langium / physics artifacts when their fingerprints change, then its `tsc -b` builds language / analytical project references before downstream fingerprints are evaluated. It does not rebuild unrelated CLI, MCP, site, or test projects.

Status: done

extension_media_build

reqlan rq/development/build.rq

Extension logo assets are generated by generate-media.mjs from logo.svg.
PNG ( `media/logo.png` ) is tracked in git and used as the packaged icon for marketplace, language file icon, and activity bar ( Azure Marketplace rejects SVG ).
WebP and SVG copies remain build outputs ( gitignored ); regenerate via `build:media` when the source logo changes.
Invoked as `pnpm run build:media` at the start of build.mjs.

extension_readme_build

reqlan rq/development/build.rq

Generate `packages/extension/README.md` from generate-readme.ts and README. template. md before VSIX packaging.
Marketplace links are resolved from phonebook.ts; changelog body comes from packages / extension / CHANGELOG. md ( Changesets output ).
Invoked as `pnpm run build:readme` at the start of build.mjs.
Requirement: extension_readme.

build_prepare

reqlan rq/development/build.rq

Copy TextMate grammars from the language package into extension syntaxes.
Sync Cursor agent skills from extension sources into `.cursor/skills`.
The orchestrator caches `build:syntaxes` independently and always runs the external Cursor-skill sync before webview and host bundling.

webview_build

reqlan rq/development/build.rq

Svelte webview UI is bundled with Vite per core.rq.
Configs: vite.config.ts, vite.config.ts, vite.config.ts
Output lands in `packages/extension/media/webviews/` for the extension host to load.
The onboarding webview inlines thanks-for-installing.template.rq via Vite `?raw` for the in-page language example; the template source stays excluded from the VSIX.
Requirement: installation_event.
Watch mode during development: `bash scripts/watch.sh` vite `--watch` alongside tsc and esbuild.

extension_typecheck

reqlan rq/development/build.rq

Extension TypeScript sources are checked with `tsc -b tsconfig.json` before bundling.
`noEmit: true` — compilation output comes from esbuild, not tsc.

extension_bundle

reqlan rq/development/build.rq

The extension host ( `src/extension/main.ts` ) and language server ( `src/language/main.ts` ) are bundled with esbuild per esbuild.mjs.
sql. js asm is emitted as `out/extension/vendor/sql-asm.cjs` and remains behind a dynamic import so the extension host entry does not parse the database engine before first paint.
Output: CommonJS `.cjs` files under `packages/extension/out/`.
`vscode` remains external; a small `Object.groupBy` polyfill is injected for older Node runtimes.

scope

reqlan rq/development/core.rq

these requirements describe the actual development of the reqlan language and tooling itself

modulurisation

reqlan rq/development/core.rq

files should be small

succinct

reqlan rq/development/core.rq

maximised meaning to character ratio .

hierarchy_of_requirements

reqlan rq/development/core.rq

user request trumps the reqlan rq requirements , and reqlan rq trump the current implementation .

stack

reqlan rq/development/core.rq

- Requirements are documented with reqlan in the reqlan rq folder.
- Language grammar is defined with langium in syntax.rq
- VSCode Extension is implemented with vscode-langium in extension
- vscode webviews are implemented with svelte
- Extension build pipeline is documented in build.rq

rust_mindset

reqlan rq/development/core.rq

- code should be complete
- nulls should be safe and deliberate
- fallbacks should be used sparingly
- incomplete code should be marked as such
- comments should describe final desired state of the code, not the current state; they should be timeless.
- tests should be local

code_comment_references

reqlan rq/development/core.rq

code comments should include reference to their respective rq references.

testing

reqlan rq/development/core.rq

tests should have comment references to the requirements they serve to test. per functional-code-comment-references.rq

stopgap

reqlan rq/distribution/distribution.rq

Stopgap distribution is at https: / / marketplace. visualstudio. com / manage / publishers / reqlan

version_management

reqlan rq/distribution/distribution.rq

Package versions are managed with Changesets via config.json.
Publishable channels ( each tag-driven ):
- Marketplace / Open VSX: extension_package ( private npm package; tagged `ext/v*` )
- GitHub Pages: site_package ( tagged `site/v*` )
- npm: `@reqlan/language`, `@reqlan/analytical`, and `@reqlan/cli` ( tagged `language/v*`, `analytical/v*`, `cli/v*` )
Internal tool `reqlan-mcp` is ignored by Changesets and marked `private` so it is never published to npm ( distributed with the extension / local MCP config instead ).
Contributors record release intent by adding a changeset file when a publishable package changes.

npm_distribution

reqlan rq/distribution/distribution.rq

npm publishing runs only when a `language/v*`, `analytical/v*`, or `cli/v*` tag is pushed.
Tags are created by deployment_flow; the npm workflow does not publish on ordinary commits.
The deploy workflow builds language / analytical / cli once, then publishes each package in sequence via `pnpm --filter <pkg> publish --access public --no-git-checks` ( language, then analytical, then cli ).
Before each package publishes, skip-already-published.mjs with `--filter <pkg>` checks the public npm registry and skips that step when the version is already published ( sets `should_publish=false` ). That avoids re-attempting already-published versions under OIDC.
Auth uses npm trusted publishing ( OIDC ) from GitHub Actions — no long-lived `NPM_TOKEN`.
Workflow requirements: `permissions.id-token: write`, Node ≥ 22. 14 with npm ≥ 11. 5. 1, registry `https://registry.npmjs.org`.
Each of `@reqlan/language`, `@reqlan/analytical`, and `@reqlan/cli` must have a Trusted Publisher on npmjs. com for GitHub Actions with org / user `littletuna4`, repository `reqlan`, workflow filename `deploy-npm.yml`, allowed action `npm publish`.
Package `repository.url` must match `https://github.com/littletuna4/reqlan.git`. Provenance attestations are generated automatically for public packages from this public repo.
Bootstrap: first publish of each scoped package can be done locally ( you must be logged in to npm as an `@reqlan` org member ) with `pnpm --filter @reqlan/language publish --access public --no-git-checks`, then analytical, then cli — or wait for the trusted-publisher CI path after packages exist and Trusted Publisher is configured.
Note: Changesets `ignore` only skips version bumps; packages must be `private: true` to skip local `changeset publish` ( `pnpm run release:npm` ) as with `reqlan-mcp` and `reqlan-extension`. CI publishes per-package and does not use `changeset publish`.
Published packages declare `publishConfig.access: public`.
Implementation: deploy-npm.yml, skip-already-published.mjs, and root `release:npm` in package.json for local changeset-based publish. Docs: trusted-publishers.

extension_package

reqlan rq/distribution/distribution.rq

The VS Code extension lives in packages / extension with npm package name `reqlan-extension` ( Marketplace / Open VSX id `reqlan.reqlan-extension` ).
Its package. json version is the authoritative Marketplace and Open VSX release version.

site_package

reqlan rq/distribution/distribution.rq

The static site lives in site / with npm package name `site`.
Its package. json version identifies site releases for tagging.

deployment_flow

reqlan rq/distribution/distribution.rq

On push to main, if pending changesets remain, the release workflow applies them with `pnpm changeset version`.
This bumps package. json for each affected package and writes changelogs.
The workflow commits the result, creates annotated tags for every bumped publishable package, and pushes the commit and tags back to main.
Release tags use `site/v{version}`, `ext/v{version}`, `language/v{version}`, `analytical/v{version}`, and `cli/v{version}` where `{version}` is the semver from that package's package. json.
Deployment is tag-driven for every channel per release_tagging; the release workflow only versions and tags.
GitHub Actions pushes with the default `GITHUB_TOKEN` do not trigger other workflows, so site and npm deploy are also invoked directly from the release workflow.
Optional `RELEASE_PAT` allows tag pushes to trigger downstream workflows for manual reruns and external CI.
Recursive runs are prevented by skipping the release workflow for release commits.
Tag patterns and downstream deploy workflows follow deployment_flow.
The implementation lives in release.yml.

release_tagging

reqlan rq/distribution/distribution.rq

Deployment is tag-driven rather than commit-driven for every publishable channel.
Tags are created automatically by deployment_flow, not manually.
Site deployments are triggered by Git tags matching `site/v*` via site_distribution.
VS Code extension publishing is triggered by Azure DevOps tags matching `ext/v*` via extension_distribution and openvsx_registry.
npm publishing is triggered by Git tags matching `language/v*`, `analytical/v*`, or `cli/v*` via npm_distribution.
The tag suffix after the channel prefix ( `site/v`, `ext/v`, `language/v`, `analytical/v`, `cli/v` ) equals the package. json version at that tag.

npm_package_readme

reqlan rq/distribution/distribution.rq

Publishable npm packages ( `@reqlan/language`, `@reqlan/analytical`, `@reqlan/cli` ) ship README. md generated from each package's `README.template.md`.
Pattern matches extension_readme: centered logo, package name, description, features, phonebook links, and Changesets changelog body.
Generated by generate-npm-package-readmes.ts via root `pnpm run build:readme`.
Contact and repository links come from phonebook via phonebook.ts per npm_package_readme_links.

extension_readme

reqlan rq/distribution/distribution.rq

The VSIX package must include a README for the Marketplace and Open VSX listings.
Contact and repository links come from phonebook via phonebook.ts per extension_readme_links.
Release notes are appended from CHANGELOG.md, which Changesets maintains per version_management.
Generated during extension build from README.template.md by generate-readme.ts per extension_readme_build.

root_readme

reqlan rq/distribution/distribution.rq

The GitHub repository README is the primary repo lander per landers.
Site, marketplace, repository, and contact links come from phonebook via phonebook.ts per root_readme_links.
Generated from README.template.md by generate-root-readme.ts.

vsix_export

reqlan rq/distribution/distribution.rq

The VSIX includes logo assets from the extension media build: PNG for marketplace icon, language file icon, activity bar, and README; WebP as a raster fallback.

site_distribution

reqlan rq/distribution/distribution.rq

GitHub Pages deployment runs only when an `site/v*` tag is pushed.
Tags are created by deployment_flow; the site workflow does not deploy on ordinary commits.
The implementation lives in deploy-site.yml.

extension_distribution

reqlan rq/distribution/distribution.rq

Azure DevOps builds, tests, packages, and publishes the VS Code extension only for tags matching `ext/v*`.
Tags are created by deployment_flow.
The extension version comes from packages / extension / package. json at the tag; the pipeline must not overwrite it from the tag suffix.
The implementation lives in azure-pipelines.yml.
VSIX packaging follows vsix_export.
Marketplace publish is complemented by Open VSX per openvsx_registry.

openvsx_registry

reqlan rq/distribution/distribution.rq

The extension should be published to the Open VSX registry at https: / / open-vsx. org so it is installable in editors that use Open VSX instead of the Visual Studio Marketplace.
Publishing should use the same tag-driven `ext/v*` releases as extension_distribution.
The packaged VSIX from vsix_export is the artifact published to Open VSX.
Azure DevOps is the authoritative publish workflow; Open VSX publish belongs in azure-pipelines.yml alongside marketplace deploy.

workflow_deduplication

reqlan rq/distribution/distribution.rq

Extension publish automation should have a single authoritative workflow to avoid duplicate marketplace releases.
Azure DevOps is the authoritative extension publishing workflow per extension_distribution and openvsx_registry.
The site remains deployed by GitHub Actions per site_distribution.
npm packages are published by GitHub Actions per npm_distribution.
Versioning and tag creation are owned by GitHub Actions per deployment_flow.

grammar_linguist

reqlan rq/distribution/distribution.rq

The grammar should be updated to use
https: / / github. com / github-linguist / linguist
Acceptance is dependent on maturity and usage.

landers

reqlan rq/distribution/landers.rq

The reqlan extension has the following entry points:
- the vsc marketplace and open vsx marketplace via the README.template.md
- npm packages via README.template.md, README.template.md, and README.template.md
- the site.
- the github repository via the README.template.md
- landers must keep cross references up to date via the phonebook.ts
phonebook

docs_reqs

reqlan rq/docs/docs.rq

the project requirements should all be documented in the the reqlan rq folder of this repo

export_docs_tag

reqlan rq/docs/docs.rq

the " @ docs " tag should be used to mark files as included in the docs .

activation

reqlan rq/extension/activation.rq

VS Code loads the extension host entry at main.ts when an activation event in package.json matches.
The exported `activate(context)` function is the single activation entry point for vscode_extension.
Install-time and first-run sequencing across extension vs base layers: installation_sequencing.
Startup failure diagnosis, first-paint sequencing, bundle splitting, and development-host lessons: startup-performance.rq.

activation_events

reqlan rq/extension/activation.rq

Activation is declared in `contributes.activationEvents` in package.json.
- `onStartupFinished` — activate after the workbench finishes starting; ensures first-run onboarding can run without opening a `.rq` file first.
- `onLanguage:reqlan` — activate when a reqlan document is opened.
- `onLanguage:python`, `onLanguage:javascript`, `onLanguage:typescript`, `onLanguage:typescriptreact` — activate for comment-reference and glue-semantics support in those languages.
- `onView:reqlan.activityBar` — activate when the Reqlan activity bar view is opened.
- `onChatParticipant:reqlan.reqlan-extension` — activate when the @ reqlan chat participant is used.
- `onCommand:reqlan.*` — activate when listed Reqlan palette commands run before the extension has loaded.
There is no separate `onInstall` hook; install-time behaviour runs on the first activation after install.

activation_sequence

reqlan rq/extension/activation.rq

`activate` is synchronous and non-blocking in main.ts; it never awaits startup work so the UI is available as soon as possible. It runs the following phases:
1. Register reference inlay-hint and CodeLens configuration / commands synchronously.
2. Call analytical_submodule_activation — registers commands, activity bar, chat, webviews, AI commands, and mutation hooks synchronously and returns without starting indexing.
3. Register import-error quick-fix commands when the analytical submodule registered.
4. Arm first_paint_startup so index startup cannot race the activity-bar shell.
5. Invoke onboarding_check without awaiting it, so onboarding cannot block activation.
Submodule failures are logged and do not prevent later phases from running.

background_startup

reqlan rq/extension/activation.rq

Startup work that must not block activation is coordinated by `scheduleBackgroundStartup` in main.ts.
- first_paint_startup gates index discovery and sync when the Context view opens; a three-second fallback preserves warm startup when the sidebar remains closed.
- The language client starts after the same paint signal when the Context view opens, with a one-second fallback so language features still start when the sidebar remains closed.
- Registers attribute and name catalog sync once the language client exists; the initial push covers an already-ready index and the catalog-update subscription covers indexes that become ready afterwards.
Index and language-client failures are logged and do not affect the already-available UI.

first_paint_startup

reqlan rq/extension/activation.rq

The activity-bar HTML shell is assigned synchronously by activity-bar-webview-provider.ts.
Its Svelte app installs the host message listener before mount, then sends the one-shot `ready` handshake from a task queued after its first animation frame.
startup-gate.ts resolves that handshake once; `IndexService.activate` then discovers bases and syncs. If no view opens, a bounded three-second fallback starts the index without any visible first paint to contend with.
Parser services inside each `WorkspaceIndex` are lazy and are created only when a file is actually parsed, not while bases are discovered.
The sql. js asm implementation is emitted as a separate lazy vendor bundle, so loading `main.cjs` does not parse the database engine before `activate`.

Status: done

analytical_submodule_activation

reqlan rq/extension/activation.rq

Analytical submodule registration is implemented in index.ts.
`activateAnalyticalSubmodule` is synchronous: VS Code contributions ( commands, activity bar provider, chat participant, webviews, AI commands, mutation hooks ) register synchronously and it returns the submodule immediately.
It does not start indexing; it passes the activity-bar post-paint callback into the provider and the caller starts index activation through first_paint_startup.

onboarding_check

reqlan rq/extension/activation.rq

Post-install onboarding is checked on every activation, not via a dedicated install event.
installation_event_trigger is satisfied because `activate` always calls open-thanks-for-installing.ts.
The check reads global state key `onboarding` via onboarding-state.ts:
- `onboardingMessageShown` — when false, open the onboarding webview panel via onboarding-panel.ts.
- `lastVersion` — updated each activation after the message has been shown so future releases can detect extension updates.
The call is fire-and-forget; errors are logged and do not fail activation.

ai_api

reqlan rq/extension/agents/features-ai.rq

should use the chat participant api . which should be in a module . that consumes analysis functions from other modules . https : / / code . visualstudio . com / api / extension-guides / ai / chat

ai_integration

reqlan rq/extension/agents/features-ai.rq

The extension should integrate with ai workflows via command palette actions and mcp tools.
Ai-facing features should prioritise token minimisation and focused context over full-graph dumps.
Command palette actions use the Reqlan category; chat slash commands and skills use the rq- prefix.

ai_build_requirement

reqlan rq/extension/agents/features-ai.rq

A command palette action ( e. g. ctrl + p: build new requirement ) should create a requirement from user or ai-provided intent.

ai_add_to_context

reqlan rq/extension/agents/features-ai.rq

A command palette action ( e. g. ctrl + p: add to context ) should add selected requirements to the ai conversation context.

ai_write_plan

reqlan rq/extension/agents/features-ai.rq

A command palette action ( e. g. ctrl + p: write plan ) should draft or update an @ plan attribute for the selected idea.

event_driven

reqlan rq/extension/architecture.rq

the application should be event driven .

state_machine_mindset

reqlan rq/extension/architecture.rq

the application should be designed as a collection of state machines ; built using zustand if in js .

code_completion

reqlan rq/extension/code_completion.rq

string and namespaces should code complete nicely based on the currnet files' path and the resolved import config.

configuration_location

reqlan rq/extension/configuration.rq

An optional `.reqlan/config.json` may appear under a base's `.reqlan` directory.
For a given `.rq` file, the applying base is the nearest ancestor directory that owns a `.reqlan` folder.
The applying config is that base's `.reqlan/config.json` when present.
If the owning base has no `config.json`, or no owning base is found, defaults from configuration_import_roots apply.
A child base does not inherit a parent base's config.
Implemented by reqlan-path-resolve.ts.

configuration_schema_file

reqlan rq/extension/configuration.rq

The machine-readable JSON Schema for `.reqlan/config.json` is config.schema.json.
The extension contributes that schema for `**/.reqlan/config.json` via `jsonValidation` in package.json.
`.reqlan/config.json` is a JSON object. Unknown properties are not part of the schema and are ignored when loading.

configuration_import_roots

reqlan rq/extension/configuration.rq

`importRoots` is an optional array of alias-to-directory mappings in `.reqlan/config.json`.
Each mapping has:
- `alias` ( required non-empty string ): prefix before `/` in aliased import paths.
- `root` ( optional non-empty string ): directory for that alias.
A relative `root` resolves against the base root ( the parent of `.reqlan` ), not against the `.reqlan` directory.
An absolute path or `file://` URI is used as that alias' import-root directory directly.
When `root` is omitted for a mapping, that alias uses the workspace folder that contains the `.rq` file.
When `importRoots` is omitted, empty, or has no valid entries, the default is one mapping with alias `@` and no explicit root.
When several aliases could match a path, the longest alias wins.
Invalid or unreadable JSON, and a non-array `importRoots` value, fall back to defaults ( or no loaded config for discovery, then defaults at resolve time ).
Language path forms and `@/` shorthand: import_paths and configuration_import_root_alias.
Schema: configuration_schema_file. Applying file discovery: configuration_location.
Editor completion of aliased import paths: code_completion.

configuration_rqignore

reqlan rq/extension/configuration.rq

Each base may define path ignore rules in `.reqlan/.rqignore` using * * gitignore syntax * *.
Patterns are relative to the base root ( parent of `.reqlan` ), not the `.reqlan` directory.
Owned by `@reqlan/analytical` so the CLI, MCP, and extension share one filter for discovery and indexing walks.
Built-in defaults always apply ( dependencies, venvs, build output, VCS / editor stores, `*.db3` / sqlite DBs, `*.secret.rq`, hidden entries, and `.reqlan/` itself ); the on-disk file adds or overrides via the same syntax, including `!` negation.
New bases seed `.reqlan/.rqignore` with those defaults ( rqignore ).
Missing or unreadable `.rqignore` still uses built-in defaults.
Location convention: configuration_location. Application memory: application_memory.

Status: done

ai_naming

reqlan rq/extension/configuration.rq

Command palette entries use category " Reqlan " with unprefixed titles ( the palette renders them as " Reqlan:... " ).
The rq- prefix is reserved for chat slash commands and agent skills only, e. g. / rq-search and / rq-build-requirement in Cursor or @ reqlan / rq-search in VS Code Copilot.
Do not put rq- or " RQ: " in command palette titles; that duplicates the visible prefix.

export_configurability

reqlan rq/extension/export_functions.rq

exports should be built in mind with a print menu that will available for user configuration.
The initial export should accept a user prompt input for a file name.
Preferred UI is export_webview rather than separate QuickPick chains per format.

export_csv

reqlan rq/extension/export_functions.rq

A command palette action should open export_webview ( or run csv export ) with tags flattened for quick filtering.
csv_export

export_JSON

reqlan rq/extension/export_functions.rq

A command palette action should open export_webview ( or run json export ).
json_export

export_html

reqlan rq/extension/export_functions.rq

A command palette action should open export_webview with HTML selected.
html_export
Host options for embedded mounts include html_export_header_link and html_export_url_base.

export_pdf

reqlan rq/extension/export_functions.rq

A command palette action should export requirements to pdf ( preserving links. ) via export_webview when available.

command_palette

reqlan rq/extension/features-commands.rq

Extension commands should be available via the vscode command palette and configurable keyboard shortcuts.
Command titles should not repeat the category prefix; use category " Reqlan " with plain titles so the palette shows " Reqlan: List All Ideas ", not " Reqlan: Reqlan:... " or " RQ: RQ:... ".

view_all_requirements

reqlan rq/extension/features-commands.rq

A command palette action should open a browsable view of all requirements in the workspace.

toggle_indirect_references

reqlan rq/extension/features-commands.rq

A command palette action should toggle display of indirect references in complementary rendering and graph views.

get_local_graph

reqlan rq/extension/features-commands.rq

A command palette action should get the local graph for the current file or selected idea.

decompose

reqlan rq/extension/features-commands.rq

A command pallete action for decomposition. Should replace an idea with a reference to a new file that holds the old contents.
Should accept multiple inputs and put them in a list.
e. g.
to ( ideainputname, defaulting to concatenation )

exports

reqlan rq/extension/features-commands.rq

graph should be exportable via the export_functions.rq

divide_and_conquer

reqlan rq/extension/features-commands.rq

A command palette action should divide and conquer the current file or selected ideaset. ( an llm prompt that takes all the context and fires off subagents )

pallete_function_create_todo

reqlan rq/extension/features-commands.rq

A function that opens up a modal webview form allowing the user to write a rq-idea, search for references etc, and writes it to a specified output file.
default folder is next to current file, but should be selectable in form.
This behaviour should be configurable via configuration.rq

add_to_chat

reqlan rq/extension/features-commands.rq

A set of command_palette functions that add the selected idea, ideaset, or file to the chat.
Commands: Add Idea to Chat, Add Ideaset to Chat, Add File to Chat ( category Reqlan ).
Uses the idea / ideaset under the cursor ( or ideas overlapping the editor selection ) when in a. rq file; otherwise QuickPick. Opens chat with # requirement / # file context, with clipboard fallback.

Status: done

open_index_diagnostics

reqlan rq/extension/features-commands.rq

Command palette action * * Open Index Diagnostics * * ( `reqlan.openIndexDiagnostics` ) opens the timing diagnostics webview for the active base.
Shows total index time, run drill-down, and per-file ranking ( duration, depth, outcome ).
Details: index_diagnostics_webview.

Status: done

open_a_random_requirement

reqlan rq/extension/features-commands.rq

as it sounds

search_code_actions

reqlan rq/extension/features-commands.rq

when cursor is in a reference, there shouls be a code action to search for references to that idea.
it should also allow wrapping a selected string, or the word at the cursor when in idea-body prose, as a new reference.
it should open up a webview modal that shows a search dialog that allows the user to search for potential references.
the search menu should preserve / show the context of the would-be reference: the rest of the containing idea, with styling, and with the selected text pulsing / styled prominently.
it should support fuzzy / partial searching. it should list the closest matches in a paginated view.
selecting the idea should fill / replace the reference ( or wrap the selection as name ) and an import ( if required ) appropiately

Status: done

graph_view

reqlan rq/extension/features-consumption.rq

The extension should provide a requirements graph view showing ideas and their references as nodes and edges.
The graph view should support navigation from a node to its source definition in the editor.
Users should be able to filter or focus the graph by file, ideaset, tag, or status.

local_graph_view

reqlan rq/extension/features-consumption.rq

The extension should provide a local graph view scoped to the current file or selected idea.
The local graph should show direct and optionally indirect references with a configurable depth.

status_table

reqlan rq/extension/features-consumption.rq

The extension should render a status table summarising ideas by lifecycle state, priority, and completion.
The status table should support sorting and filtering by tags and attributes.

ide_page_reports

reqlan rq/extension/features-consumption.rq

The extension should provide dedicated report pages rendered inside the ide.
Report pages should include at minimum a graph page and a status table page.
Report pages may render computed information that is not present as literal text in source files.

export_webview

reqlan rq/extension/features-export.rq

The extension should provide a single export webview for exporting the requirement graph in various formats ( json_export, csv_export, html_export, and later formats such as pdf ).
This generalizes the current HTML-only html_export_form: format choice is primary, and format-specific options ( e. g. HTML runtime mode, template, page families ) appear when that format is selected.
Shared options: scope, output folder, and export name; defaults persist to application_memory as `export_settings.json` under `<workspace>/.reqlan/`.
While an export runs, the form should show a loading state with live progress ( phase message and, when known, completed / total or percent ) so the user can see HTML ( and other formats ) being built — not only a disabled button.
The user should be able to open it from:
- a link / control in the main ideas_summary chrome ( status bar or header )
- the command_palette

Status: partial

json_export

reqlan rq/extension/features-export.rq

The extension should export the requirement graph as structured json for tooling and ai consumption.

csv_export

reqlan rq/extension/features-export.rq

The extension should export requirements as csv with tags and key attributes flattened into columns.

index_ideas

reqlan rq/extension/features-graph-analysers.rq

Each base maintains an index of its ideas for fast lookup and navigation ( index ).
The index should update incrementally as. rq files change within that base ( nested child bases excluded ).
Persistence lives in application_memory per base, shared with CLI and MCP — not VS Code extension storage.
Engine ownership: workspace-index.ts in `@reqlan/analytical`; multi-base via BaseRegistry; editor watches via index-service.ts.

index_technology

reqlan rq/extension/features-graph-analysers.rq

The index_ideas graph database is sql. js SQLite, aligned with graph_design.
On-disk location is application_memory ( `<base>/.reqlan/ideas-index.sqlite` ), not `context.globalStorageUri`.
Implementation: application-memory.ts, workspace-index.ts, headless create-runtime.ts for CLI / MCP, and index-service.ts for the VS Code host.

indexing_incrementality

reqlan rq/extension/features-graph-analysers.rq

Indexing should be incremental: watcher-driven single-file updates, and soft full syncs that skip unchanged files by stored mtime.
Hard rebuilds reparse everything. Detail and UX ( progress, cancel, non-blocking UI ): nonblocking_index.

indexing_trigger_filesave

reqlan rq/extension/features-graph-analysers.rq

indexing should be triggered by . rq file create / change / delete via watchers .

indexing_trigger_manual

reqlan rq/extension/features-graph-analysers.rq

indexing should be triggered by manual indexing commands ( Refresh / Clear & rebuild ) .

indexing_trigger_open

reqlan rq/extension/features-graph-analysers.rq

After the activity bar's first painted frame / base activate, run one soft sync ( mtime-skipped ) so the index is warm without delaying the sidebar shell.
This is a startup pass — not the idle checker ( indexing_trigger_auto ).

indexing_trigger_auto

reqlan rq/extension/features-graph-analysers.rq

When the editor host is idle, run a * * background staleness check * * — not a reindex and not a soft full sync UI pass.
Philosophy: computationally cheap. Load document mtimes in * * one * * SQLite read, compare each file's FS mtime in memory, and only then index mismatched or new files; drop deleted docs in one batched delete.
A single MAX ( mtime ) watermark is not sufficient ( one file can get newer while another gets older ).
If nothing is stale: no state transition, no progress UI, no parse.
If some files are stale: index * * only those files * * under nonblocking_index.
Schedule after a quiet period with no index activity; prefer running when the window is unfocused; defer or cancel if the user becomes active again.
Extension host only ( index-service.ts ); CLI / MCP have no idle loop ( they sync on activate / command ).

Status: done

list_all_ideas

reqlan rq/extension/features-graph-analysers.rq

The extension should provide a command to list all ideas in the workspace with file location and summary.

index_comment_reference_inclusion

reqlan rq/extension/features-graph-analysers.rq

The reqlan-comment.langium comments should be included as a node type in the index

file_related_requirements

reqlan rq/extension/features-graph-analysers.rq

The extension should provide a view or command to get requirements relating to the currently open file.
File-related lookup should follow both explicit file references and comment rq: links in that file.

deprecation_impact_analysis

reqlan rq/extension/features-graph-analysers.rq

The extension should analyse the impact of deprecated ideas on dependent requirements.
Deprecation analysis should report downstream ideas that reference or depend on deprecated items.

git_dates

reqlan rq/extension/features-graph-analysers.rq

The extension should surface creation and last-modified dates for ideas via git history where available.

completion_tracking

reqlan rq/extension/features-graph-analysers.rq

The extension should track and surface completion, outstanding work, and open issues across the requirement graph.
Completion tracking should derive from @ status, @ tags, and other lifecycle attributes where present.

local_graph_analysis

reqlan rq/extension/features-graph-analysers.rq

The extension should provide a function to access a small slice of the graph around a given idea.

semantic_analysis

reqlan rq/extension/features-graph-analysers.rq

Search graph for ideas related to a given idea or ideaset.

graph_design

reqlan rq/extension/features-graph.rq

the graph should be a graph with nodes representing ideas and files and edges representing references.

html_export

reqlan rq/extension/features-html-export.rq

The extension should support building documentation as html from the requirement graph.
Html export should render ideas, attributes, references, and navigable structure suitable for sharing.
Core export pipeline lives in `@reqlan/analytical` ( `exportHtml` / `AnalysisApi.exportHtml` ); the extension command palette and CLI ( `reqlan export` ) are thin hosts.
A command palette action ( and the Ideas Summary link ) should open export_webview with HTML selected and export requirements to html as a multi-file static site ( single-file mode remains optional via html_export_runtime_modes ).
HTML-specific form fields live under html_export_form within that general export webview.
html_export_form
html_export_multi_file
html_export_internal_links
html_export_search
html_export_list_views
html_export_idea_pages
html_export_file_pages
html_export_code_reference_pages
html_export_cluster_pages
html_export_graph_page
html_export_attributes_index
html_export_attribute_pages
html_export_printable_pages
html_export_runtime_modes
html_export_scrollable_lists
html_export_header_link
html_export_url_base

html_export_form

reqlan rq/extension/features-html-export.rq

HTML export options are hosted inside the general export_webview ( not a separate HTML-only panel long-term ).
When format is HTML: simple options include scope, output folder, export name, and runtime mode.
Advanced HTML settings should be collapsed by default behind an expandable section ( template, cluster strategy, page-family toggles, file filters, url base, header link, print entry, neighbourhood graph node cap ).
File filters: exclude `*.secret.rq` ideas ( `excludeSecretFiles` ) and / or exclude paths matched by `.reqlan/.rqignore` ( `excludeIgnoredFiles` ); both default off so indexed ideas from those files are included unless opted out.
Form defaults persist to application_memory as `export_settings.json` under `<workspace>/.reqlan/` ( shared with other export formats ).
Saving settings or running export writes that file; reopening the form reloads the last values.
HTML export still calls `@reqlan/analytical` `exportHtml` with an `ExportRequest` built from the form.
While export runs, the webview shows progress from the analytical pipeline ( snapshot phases, then write completed / total ) via `exportProgress` messages — see export_webview.
Current implementation is HTML-only and should be generalized; until then the existing panel satisfies the HTML path.

Status: partial

html_export_multi_file

reqlan rq/extension/features-html-export.rq

Html export should generate a multi-file static site rather than a single document.
The export should include page families for overview, ideas, files, code files, clusters, attributes, graph, data, and print-focused pages.

html_export_internal_links

reqlan rq/extension/features-html-export.rq

Every exported idea should have a stable html page path and stable in-page anchors.
References, breadcrumbs, search results, graph nodes, cluster members, attribute listings, file listings, and code-file listings should link to html pages rather than only showing text labels.
Graph node links must follow html_export_graph_links.
When html_export_url_base is set, those same links must be root-relative under the mount prefix so static hosts resolve them with or without a trailing slash.

html_export_search

reqlan rq/extension/features-html-export.rq

The interactive html export should provide a global search bar and page-local search bars.
Search should work offline from generated data bundled with the export.
Attribute keys and values should be searchable alongside ideas, files, code files, and clusters.

html_export_list_views

reqlan rq/extension/features-html-export.rq

Html export should provide searchable list views for ideas, files, code files, references, clusters, and attributes.
List views should preserve the usability of the current ideas summary tables with counts, sorting, filters, and quick navigation.
Every interactive table column should be sortable by header click and filterable with a per-column filter, in addition to any page-level search bar.
Long lists that sit above other page content follow html_export_scrollable_lists.
html_export_attributes_index
html_export_file_pages
html_export_code_reference_pages
html_export_scrollable_lists

html_export_idea_pages

reqlan rq/extension/features-html-export.rq

Html export should generate a dedicated page per idea.
Idea pages should include summary, attributes, inbound references, outbound references, nearby context, and links to related ideas, files, clusters, graph views, and printable forms.
Status and tags are nullable attributes: render them only when present.

html_export_file_pages

reqlan rq/extension/features-html-export.rq

Html export should generate dedicated pages for reqlan source files that host ideas in the export scope.
File pages should list hosted ideas, related clusters, and a local graph view when available.
Emission defaults on and is controllable via includeFilePages so page families can be flagged in or out without changing the export pipeline shape.
Graph nodes and idea source-file links for hosting files should resolve to these pages when enabled.

html_export_code_reference_pages

reqlan rq/extension/features-html-export.rq

Html export should generate dedicated pages for outbound file_reference targets that are not idea-hosting reqlan files already covered by html_export_file_pages.
Code-file pages should list referencing ideas and reference labels, and participate in search and navigation.
Emission defaults on and is controllable via includeCodeFilePages so this page family can be flagged in or out later.
Outbound reference path cells and graph external file nodes should link to these pages when enabled.

html_export_cluster_pages

reqlan rq/extension/features-html-export.rq

Html export should support cluster pages that group related ideas.
Deterministic clusters should at least include file, folder, tag, and status groupings.
Optional computed clusters should use graph or semantic analysis when available without making export correctness depend on them.

html_export_attributes_index

reqlan rq/extension/features-html-export.rq

Html export should provide a searchable attributes index page listing every attribute key used in the export scope.
Each attribute entry should summarize distinct values and idea counts, and link to the dedicated attribute page when html_export_attribute_pages is enabled.

html_export_attribute_pages

reqlan rq/extension/features-html-export.rq

Html export should generate a dedicated page per attribute key used in the export scope.
Attribute pages should show a distribution of distinct values ( counts and share of ideas ), and a searchable full list of ideas that declare the attribute with their values for that key.
Emission defaults on and is controllable via includeAttributePages so this page family can be flagged in or out without changing the export pipeline shape.
The attributes index, idea attribute tables, and search results should link to these pages when enabled.

html_export_graph_page

reqlan rq/extension/features-html-export.rq

Html export should provide an interactive graph page with search, filters, and links back into idea and cluster pages.
The graph should support scoped views for workspace, file, cluster, and idea contexts.
The workspace graph page must include every idea in the export scope — blocks, oneliners, and ideasets — and must not apply the interactive Ideas Summary GRAPH_MAX_NODES budget.
Ideasets are visible by default with a Hide ideasets / Show ideasets toggle, matching the external-file visibility control.
Status and tag filters are multi-select and distinguish graph_status_tag_filters.
Per-idea, per-file, and per-cluster neighbourhood graphs may still use a capped budget for focused pages.
html_export_graph_links
html_export_graph_layout
html_export_graph_animation
html_export_graph_subject
html_export_graph_labels
html_export_graph_label_modes
html_export_graph_label_auto
html_export_graph_interaction
html_export_graph_metadata

html_export_graph_links

reqlan rq/extension/features-html-export.rq

Graph node hrefs must resolve to idea pages from every export page depth, including nested idea, file, and cluster pages.
Node urls should be export-root-relative so path segments such as ideas / are not dropped when resolving from nested pages.
When html_export_url_base is set, runtime resolution of those urls must honour the mount prefix ( same contract as page and asset hrefs ).
External file nodes should resolve to html_export_file_pages or html_export_code_reference_pages when those page families are enabled.

html_export_graph_layout

reqlan rq/extension/features-html-export.rq

The interactive export graph should lay out nodes so labels and circles do not heavily overlap.
Initial placement should settle with the same Obsidian-style force model as layout_physics ( central gravity, edge springs, inverse-square repulsion ).
Rendering uses canvas 2 d ( not SVG DOM ) with shared physics from physics-core.js.

html_export_graph_animation

reqlan rq/extension/features-html-export.rq

Live physics in the HTML export should match Ideas Summary animatePhysics: continuous damped semi-implicit Euler using the defaults from physics-core.js ( same module as graph-physics.ts ).
A Live physics toggle pauses and resumes the same simulation state ( default off ); when off, the graph batch-settles then sleeps.
Simulation should converge and sleep when calm, waking on filter changes or when Live physics is turned back on, aligned with layout_physics.
Large graphs use a spatial grid + repulsion cutoff in the shared core; all nodes and full labels remain visible.

html_export_graph_subject

reqlan rq/extension/features-html-export.rq

When a graph view has a subject or center idea, that node should be visually distinct from peers and externals.
Subject styling should use the brand rust accent against cyan peer nodes.

html_export_graph_labels

reqlan rq/extension/features-html-export.rq

HTML export canvas graphs implement shared graph_labels ( full names, no ellipsis truncation ).
html_export_graph_label_modes
html_export_graph_label_auto

html_export_graph_label_modes

reqlan rq/extension/features-html-export.rq

Export-surface wiring for graph_label_modes: Labels control on every interactive export graph cycles auto / on / off; Reset restores auto.

Status: done

html_export_graph_label_auto

reqlan rq/extension/features-html-export.rq

Export-surface wiring for graph_label_auto: canvas paint applies continuous zoom opacity ( GRAPH_LABEL_FADE_START → GRAPH_LABEL_FADE_END ); hover / drag stays fully opaque.
Zoom and Fit from html_export_graph_interaction / manual_reframe update opacity each paint.

Status: done

html_export_graph_interaction

reqlan rq/extension/features-html-export.rq

The interactive export graph should support dragging nodes and panning or zooming the viewport, aligned with view_controls and manual_reframe.
Click-through to idea pages must remain available after drag via click-versus-drag discrimination.
A Fit control should reframe the viewport to the current node set without restarting layout or clearing live physics state.
Zoom and Fit must continuously drive graph_label_auto / html_export_graph_label_auto opacity when Labels is in auto mode.

html_export_graph_metadata

reqlan rq/extension/features-html-export.rq

Graph nodes in the HTML export should surface tags, status, and attribute keys on or beside the node, not only as filter inputs.
Attribute values declared on the idea should be reachable from the graph via the idea page and on-node attribute key summary.

html_export_printable_pages

reqlan rq/extension/features-html-export.rq

Html export should provide static printable pages alongside the interactive site.
Print pages should not depend on the interactive javascript bundle.
Status and tags are nullable: when absent, printable sheets must omit those fields rather than inventing placeholders such as unspecified or empty dashes.
When print pages are browsed in interactive runtime mode, long lists with content below them follow html_export_scrollable_lists.

html_export_runtime_modes

reqlan rq/extension/features-html-export.rq

Html export should support a richer interactive site mode and a leaner document or print-oriented mode from the same export manifest.
Template identifiers should select real rendering behavior rather than metadata only.
Scrollable list viewports from html_export_scrollable_lists apply only in interactive mode; document and print modes keep full-length lists.

html_export_scrollable_lists

reqlan rq/extension/features-html-export.rq

In interactive runtime mode, long list and table sections that have additional content below them should render inside a scrollable viewport with a max height so lower sections remain reachable without endless page scrolling.
Toolbar titles and filters for those sections should stay outside the scroll viewport.
In document and print runtime modes, those same lists should expand to their full natural height so the export remains readable as a continuous document and suitable for printing.
Browser print of interactive pages should also expand constrained lists to full height.

html_export_header_link

reqlan rq/extension/features-html-export.rq

Html export should accept an optional header link ( href + label ) rendered in the topbar ahead of section navigation.
Hosts such as the marketing site build can set this so readers can return to the parent site from any exported page.
When omitted, the topbar shows only the export section nav.
Site embed consumption: spec_html_export.
Often paired with html_export_url_base when the export is mounted under a parent static site.

Status: done

html_export_url_base

reqlan rq/extension/features-html-export.rq

Html export should accept an optional urlBase mount prefix ( for example `/spec` or `/reqlan/spec` ).
When set, page and asset hrefs must be root-relative under that prefix so static hosts resolve correctly whether the directory URL includes a trailing slash.
When omitted, exports keep document-relative hrefs suitable for local folder browsing.
Applies across html_export_internal_links and html_export_graph_links; site embed consumption: spec_html_export.
Often paired with html_export_header_link when the export is mounted under a parent static site.

Status: done

index_diagnostics

reqlan rq/extension/features-index-diagnostics.rq

Indexing performance diagnostics: measure and inspect time spent indexing a index base.
Timing is persisted in a dedicated * * diagnostic index * * under application memory ( index_diagnostics_store ), not in `ideas-index.sqlite`, so history survives Clear & rebuild.
Surfaces: index_diagnostics_webview. Owned by `@reqlan/analytical` for recording; the extension hosts the webview.

Status: done

index_diagnostics_metrics

reqlan rq/extension/features-index-diagnostics.rq

For each sync / index run on a base, record:
- wall-clock * * sum / total duration * * of the pass
- * * file count * * ( visited ), skipped-by-mtime count, indexed ( parse / persist attempted ) count, error count
- * * average path depth * * of visited files ( segments under the base root )
- per-file * * duration * * and outcome ( `mtime_skip` | `mtime_refresh` | `hash_skip` | `persisted` | `error` )
Runs are attributable to a trigger ( `soft_sync` | `rebuild` | `enqueue` | `stale` ).
Instrumentation wraps workspace-index.ts soft sync and nonblocking_index single-file paths via index-diagnostics-store.ts.

Status: done

index_diagnostics_webview

reqlan rq/extension/features-index-diagnostics.rq

An editor webview panel displays index timing diagnostics for the active base.
Capabilities:
- Base / latest-run summary: total time, file counts, average depth
- Drill into recent runs
- Rank files by duration ( slowest first ); show outcome and path depth
Opened by command `reqlan.openIndexDiagnostics` ( open_index_diagnostics ).
Optional entry from workspace index health ( workspace_pane ) may link later; command is the primary entry.
Implementation: index-diagnostics-panel.ts, App.svelte.

Status: done

create_requirement

reqlan rq/extension/features-mutation-hooks.rq

The extension should provide a command to create a new requirement idea in an appropriate. rq file.
New requirement creation should offer sensible defaults for name, body, and file placement.

split_requirement

reqlan rq/extension/features-mutation-hooks.rq

The extension should provide a command to split one requirement into two or more separate ideas.
Splitting should preserve references and attributes according to user selection.

copy_requirement

reqlan rq/extension/features-mutation-hooks.rq

The extension should provide a command to copy an idea or requirement to another file or ideaset.
Copy should optionally rewrite local references to match the destination context.

merge_requirements

reqlan rq/extension/features-mutation-hooks.rq

should combine requirement attributes, and any references through the codebase.

rename_file

reqlan rq/extension/features-mutation-hooks.rq

this should update any referencess in rq files ( imports, inline references, etc )
it should also update any inline references in functional code files - per features-code-comment
See also refactor_file_moves and refactor_changes.
Implemented by file-move-plan.ts, file-path-rewrite.ts, and collect-inbound-referencers.ts.

move_file

reqlan rq/extension/features-mutation-hooks.rq

if a file is moved, a prompt should be shown to the user to update any references in the file to the new path.
if multiple files are moved there should be only one prompt.
the trigger should only happen if the reqlan file has inbound or outbound references, or the non-reqlan file has inbound reqlan references.
" reqlan wants to make refactoring changes to your codebase. Do you approve? "
" yes ", " no ", " view changes "
See also refactor_file_moves.
Implemented by register-file-mutation-hooks.ts, show-mutation-approval.ts, and file-mutation-gate.ts.

references_in_functional_code_comments

reqlan rq/extension/features-non-rq-code-comment/functional-code-comment-references.rq

Comments in functional code should be able to reference reqlan ideas using the an `rq:` prefixed to an idea: `rq:idea` as demonstrated in python, but actually applicable to any language's comment context:

mcp_tools

reqlan rq/extension/features-skills-and-mcp.rq

The extension or companion server should expose mcp tools for ai and automation clients.
Headless index storage follows application_memory ( `<base>/.reqlan` ), shared with the extension and CLI.

mcp_tools_prompt

reqlan rq/extension/features-skills-and-mcp.rq

An mcp tool should provide a prompt-oriented entry point for working with the requirement graph.

mcp_keyword_search

reqlan rq/extension/features-skills-and-mcp.rq

An mcp tool should search requirements by keyword across idea names, bodies, and attributes.

mcp_tree_interrogation

reqlan rq/extension/features-skills-and-mcp.rq

An mcp tool should describe and interrogate the requirement tree for a given root idea or file.

mcp_tree_summarisation

reqlan rq/extension/features-skills-and-mcp.rq

An mcp tool should summarise a requirement subtree for compact ai context.

mcp_interaction_discovery

reqlan rq/extension/features-skills-and-mcp.rq

An mcp tool should discover available interactions, commands, and query patterns for the requirement graph.

skill_namespace_references

reqlan rq/extension/features-skills-and-mcp.rq

backslash references to skills based on the namespace should be supported.

cursor_skills_install

reqlan rq/extension/features-skills-and-mcp.rq

A command palette action ( e. g. ctrl + p: reqlan install cursor skills ) should copy rq- * skills from the extension into the workspace. cursor / skills folder and update. cursor / mcp. json when the local mcp server is available.
Place in install sequencing ( workspace agent files, not `.reqlan` ): workspace_agent_files.

chat_skill_naming

reqlan rq/extension/features-skills-and-mcp.rq

Cursor and Copilot chat skills and slash commands should use the rq- prefix, e. g. rq-search and rq-build-requirement.
This prefix must not appear in command palette titles; palette entries use category Reqlan only.

simple_views

reqlan rq/extension/features-views.rq

- table of ideas
- title,
- path / namespace,
- main attribute
- other attributes
- count of references
- table of references
- path / namespace of reference to idea
- path / namespace of referenced idea
- is in in rq ( bool )
- reference type ( file, comment, sub-idea )

git_based_history

reqlan rq/extension/git-codelens.rq

there should be a code lens button for viewing an idea history through git.
Should accept close matches and likeley file moves
should consume the same state as the context_scope

installation

reqlan rq/extension/installation.rq

Reqlan installation has * * two sequenced layers * * that must not be conflated:
1. extension_installation — host product ( VS Code / Cursor extension ) install and first activation.
2. base_installation — marking a filesystem directory as a reqlan base and seeding its `.reqlan` application memory.
Extension install alone does * * not * * create a base. Base install alone does * * not * * open the welcome webview or install host agent skills.
CLI `init` shares the base path with the editor ( init / create_base_onboarding ).

installation_sequencing

reqlan rq/extension/installation.rq

End-to-end first-run story ( typical editor user ):
1. User installs the extension from Marketplace / Open VSX / VSIX ( extension_installation ).
2. Host fires an activation_events match ( usually `onStartupFinished` ).
3. activation_sequence synchronously registers contributions and schedules background_startup; onboarding_check may open installation_event ( Welcome to Reqlan webview ) without blocking activation.
4. If no `.reqlan` exists under workspace folders, surfaces offer create-base ( create_base_onboarding ) — user-driven, never auto-created on extension install.
5. base_installation seeds config / ignore / marker; index activate / sync follows ( application_memory ).
6. Optionally, user runs Install Cursor Skills ( workspace_agent_files ) — copies rq- * skills and may update `.cursor/mcp.json`; independent of `.reqlan` seeding.
Ordering constraint: steps 1 – 3 are extension-scoped; steps 4 – 5 are base-scoped; step 6 is workspace agent tooling scoped to the open folder, not the `.reqlan` directory.

extension_installation

reqlan rq/extension/installation.rq

Extension-level install covers packing, activation, and first-run host UX — not base filesystem state.
There is * * no * * VS Code `onInstall` API; install-time behaviour runs on the * * first * * activation after install ( activation_events ).
Sequencing inside `activate` is owned by activation_sequence:
- Sync register CodeLens / inlay config commands.
- Synchronously register analytical submodule contributions ( commands, activity bar, chat, webviews, AI commands, mutation hooks ) without starting the index ( analytical_submodule_activation ).
- Register import quick-fixes, then schedule index and language-client startup through first_paint_startup / background_startup; sync catalogs once the language client exists.
- Fire-and-forget onboarding_check → welcome_webview_install.
Failures in submodule or language client are logged and must not abort later phases or the welcome check.
Related command surfaces: Show Onboarding ( show_onboarding_command ), Install Cursor Skills ( cursor_skills_install ), Create Base ( create_base_onboarding ).

welcome_webview_install

reqlan rq/extension/installation.rq

The * * Welcome to Reqlan * * onboarding webview is the extension-install UX surface.
Opened once on first activation when `onboardingMessageShown` is false ( installation_event / installation_event_trigger / onboarding_state ).
Content: welcome copy, resolved phonebook links, syntax-highlighted example `.rq`, open-as-untitled control, activity bar / `@reqlan` tips, sponsor thanks.
Must not block activation_sequence; errors are logged only.
Reopen on demand via show_onboarding_command without resetting shown state unless product policy changes.
Implementation: open-thanks-for-installing.ts, onboarding-panel.ts, onboarding.

Status: done

workspace_agent_files

reqlan rq/extension/installation.rq

Agent / AI host files are * * workspace * * artefacts, not files under `.reqlan/`.
Install Cursor Skills ( cursor_skills_install ) copies bundled `rq-*` skills into `<workspace>/.cursor/skills/` and updates `<workspace>/.cursor/mcp.json` when the local MCP server is available ( install-cursor-skills.ts ).
Requires an open workspace folder; does not create a base and does not write into `.reqlan`.
Naming: skills / chat slash commands use `rq-` prefix ( chat_skill_naming ); command palette stays category " Reqlan " ( ai_naming ).
AI command surfaces that depend on skills being present: ai_integration, ai_build_requirement, ai_add_to_context, ai_write_plan.
Dev sync of the same skill sources into this repo's `.cursor/skills` is a build concern ( build.rq ), distinct from end-user install sequencing.

base_installation

reqlan rq/extension/installation.rq

Base-level install marks a directory as a base and seeds shared application memory under `<base>/.reqlan/` ( application_memory ).
Entry points ( same helper create-base.ts ):
- Editor: `reqlan.createBase` / empty-state CTAs ( create_base_onboarding ) — only after discovery finds * * zero * * bases; never on extension install alone.
- CLI: `reqlan init directory` ( init ).
Idempotent: existing `.reqlan` is left alone ( `created: false` ).
On * * new * * base creation the sequence is:
1. Create `<base>/.reqlan/` marker directory ( presence = base ).
2. Seed base_config_seed ( `.reqlan/config.json` ).
3. Seed base_rqignore_seed ( `.reqlan/.rqignore` ).
4. Editor rediscovers bases and activates indexing for that base; SQLite `ideas-index.sqlite` appears when the index opens ( not necessarily written at marker creation ).
Child / nested bases follow base_nesting; each base owns its own `.reqlan` seeds and index.

base_config_seed

reqlan rq/extension/installation.rq

New bases write a minimal `.reqlan/config.json` ( `{}` today ) via create-base.ts.
Semantics and discovery of applying config: configuration_location, configuration_import_roots, base_configuration.
Schema / editor validation: configuration_schema_file.
A child base does not inherit a parent base's config file.

base_rqignore_seed

reqlan rq/extension/installation.rq

New bases write `.reqlan/.rqignore` with gitignore-syntax defaults ( dependencies, venvs, build output, DBs such as `*.db3`, secrets, hidden entries, `.reqlan/` itself ).
Built-in defaults always apply even if the file is missing; the seeded file is the editable surface ( configuration_rqignore / rqignore ).
Used by analytical discovery and indexing walks ( CLI and extension share `@reqlan/analytical` ).

base_vs_extension_boundary

reqlan rq/extension/installation.rq

Clear ownership so install steps do not write to the wrong store:
- Extension package / activate / welcome webview → extension_installation ( extension host + `globalState` onboarding key ).
- Activity bar, LSP, chat participant, Ideas Summary → extension runtime after activation_sequence.
- `.reqlan/` marker, `config.json`, `.rqignore`, ideas index, index diagnostics sqlite → base_installation under `<base>/.reqlan/`.
- Cursor `rq-*` skills + MCP json → workspace_agent_files under `<workspace>/.cursor/`.
Do not store agent skills or MCP config inside `.reqlan`. Do not treat welcome-webview globalState as base-local memory.

remote_imports

reqlan rq/extension/language-support/features-imports.rq

Reqlan files should support importing requirements from remote urls.
Remote import syntax should follow import " https: / / company. com / reqs / style. rq " as styleguide.
The extension should resolve, cache, and validate remote imports.
Barrel imports should be recommended for token efficiency when many symbols are needed from one remote file.

from_import_syntax

reqlan rq/extension/language-support/features-imports.rq

Multiple symbols should be allowd to be be imported with `from "path" import symbol1, symbol2, symbol3` syntax.

import_error

reqlan rq/extension/language-support/features-imports.rq

" Could not resolve reference " errors offer Quick Fix code actions ( lightbulb and editor right-click Quick Fix ).
Fixes:
- Add import from a matching idea found in loaded documents or the name catalog pushed from the index
- Rewrite the reference to an anonymous qualified form `name`
- Search the index for matching ideas, ideasets, or files ( QuickPick ), then insert an import
- Create the idea in a new. rq file and import it
general_errors
code_actions
quick_fixes

implicit_file_extension

reqlan rq/extension/language-support/features-imports.rq

The import statements should not require an extension, i. e. it should assume ". rq " unless otherwise specified.
An extensionless path resolves to the ". rq " file first, then to a literal extensionless file.
A path that already carries any extension is resolved exactly as written.

import_code_completion

reqlan rq/extension/language-support/features-imports.rq

Import path code completion for `import` / `from` strings ( and shared anonymous paths ).
code_completion
import_code_completion_explicit_extension
import_code_completion_path_segments
import_code_completion_substring_match
import_code_completion_ranking
anonymous_reference_code_completion

import_code_completion_explicit_extension

reqlan rq/extension/language-support/features-imports.rq

Completions insert paths with an explicit `.rq` extension. implicit_file_extension
Hand-written imports may still omit the extension; completion prefers the written form with `.rq`.

import_code_completion_path_segments

reqlan rq/extension/language-support/features-imports.rq

In a folder context, show next path segments ( directories with a trailing `/` ).
After `../`, offer `../path/` before nested `../path/file.rq`.

import_code_completion_substring_match

reqlan rq/extension/language-support/features-imports.rq

Filter path candidates by search within the path, not only a starts-with prefix.
Typing `path` should match `../../parent/path.rq`.
Typing `hellopath` should match `../../hello/inbetween/path/file.rq` ( characters matched in order across path segments ).

import_does_not_exist_error

reqlan rq/extension/language-support/features-imports.rq

Imports show an underline error when the target file does not exist.
Imports also show an underline error when a named imported idea does not exist in the target file.
general_errors

import_code_completion_ranking

reqlan rq/extension/language-support/features-imports.rq

Rank import path completions by directory proximity ( hop count from the completing file's directory to the candidate's directory ), then directories before files, then path alphabetically.
Example: typing `../` ranks `../close.rq` before `../../../path.rq`.
Emit sortText for that order, and set filterText so the editor does not re-rank by label fuzzy score over proximity.

anonymous_reference_code_completion

reqlan rq/extension/language-support/features-imports.rq

Anonymous imports should share the same code completion
e. g. code_completion.rq should complete the same as `import "@/reqlan rq/extension/code_completion.rq" as code_completion`. they should share the same code and logic

general_errors

reqlan rq/extension/language-support/language-server-errors.rq

error messages should be deliberate and developer friendly.
recommendations should be offerred where appropriate.

graph_library

reqlan rq/extension/library/graph.rq

Reusable cytoscape-based graph visualization library for force-directed and compound graphs.
Provides a mount → sync slice → layout → optional live physics → destroy lifecycle with a simplified API.
Implementation lives in graph-cytoscape.ts, graph-cy-controller.ts, graph-cy-elements.ts, graph-cy-interactions.ts, graph-cy-highlight.ts, graph-physics.ts, graph-groups.ts, and graph-theme.ts.
Ideas Summary re-exports the shared modules from lib for backward-compatible import paths.
Consumers pass a node / edge slice and sync options; the library owns the cytoscape instance, diffing, layout runs, and optional continuous physics.

technology

reqlan rq/extension/library/graph.rq

uses cytoscape. js for the graph layout and canvas.
cytoscape-fcose provides the batch force-directed settle; cytoscape-cola is available as a batch layout option.
continuous ( " live " ) physics is a custom simulation in graph-physics.ts.
the controller initialises cytoscape with Canvas 2 D only ( pixelRatio 1, no WebGL ) so webviews do not break on unresolved CSS variables.
Body prose with inline parentheses must parse per lists and round_brackets.

graph_cytoscape

reqlan rq/extension/library/graph.rq

builds cytoscape elements and stylesheet from a generic node / edge slice.
registers batch layout options ( fcose, cola, breadthfirst, circle, concentric, grid, random ) and seeds positions for new nodes.
exposes CompoundBasis ( single-membership folder tree ) and GroupBasis ( flat multi-membership ) as grouping inputs.
per graph-cytoscape.ts and graph-theme.ts.
getLayoutConfig sets fit: false for initial ( mode = = = ' initial' ) batch layouts so auto_reframe owns the first viewport fit; relayout modes may still fit via the layout algorithm.

graph_cy_controller

reqlan rq/extension/library/graph.rq

the cytoscape object should use event driven patterns; lifecycle is documented here.
GraphCyController in graph-cy-controller.ts owns the cytoscape instance with inline lifecycle state ( idle, syncing, layouting, physics ).
syncGeneration cancels stale layout callbacks when the slice changes mid-layout.
Selection and drag-pinned positions are tracked in userPositionedNodes on the controller.
syncSlice diffs elements ( add / remove / update the delta ) via graph-cy-elements.ts so surviving nodes keep positions; requestLayout restarts the active algorithm and clears user pins.
Pointer / selection wiring lives in graph-cy-interactions.ts; compound hover / selection in graph-cy-highlight.ts.
Live physics is the custom simulation in graph-physics.ts; one instance persists with the cytoscape instance and is paused / resumed, never rebuilt. Grabbing a node pins it in the running sim ( its live position keeps exerting forces ); release unpins with no restart and no snap.
ResizeObserver debounces cy. resize ( ) and re-triggers a pending sync when the container gains size.
Mount only while the graph container is visible and non-zero — do not keep cytoscape alive under display: none; WebGL init on a zero-size hidden container can break the host webview before messaging is attached.
Viewport fitting per reframe_view; tracks lastSyncedNodeSetKey vs fittedNodeSetKey to drive auto_reframe.
Label visibility per graph_label_modes / graph_label_auto: setLabelMode updates text-opacity from zoom ( and hover / drag force-opaque in auto ).

graph_cy_elements

reqlan rq/extension/library/graph.rq

syncGraphElements diffs the live cytoscape graph against the desired slice rather than remove-all / add-all on every sync.
Surviving nodes keep positions; only added / removed / updated elements move.
Mutable data fields ( label, color, flags ) can update without a structural relayout.
per graph-cy-elements.ts.

webview_threading

reqlan rq/extension/library/graph.rq

VS Code webviews run JavaScript on a single main thread, like a browser tab.
Heavy synchronous work — cytoscape layout iterations, large element builds, unbounded loops — blocks UI updates until it finishes.
Layout iteration count scales with node count ( capped ) rather than running unbounded defaults.
Do not restart layout synchronously on layoutstop; hand off to the graph-physics simulation, which integrates one step per requestAnimationFrame instead of blocking.

layout_physics

reqlan rq/extension/library/graph.rq

defaults to force-directed layout ( fcose ) with animation on, but callers can select other options offered by cytoscape. js.
a toggle leaves layout animation and live physics on for force-directed layouts instead of settling immediately.
live physics is the custom obsidian-style simulation in graph-physics.ts ( force core: physics-core.js ), regardless of which force-directed batch layout produced the initial settle.
forces are central gravity toward the centroid, linear edge springs, and inverse-square node repulsion; every childless node participates, including disconnected orphans.
group container constraints live in graph-groups.ts: each leaf carries data ( ' groupIds' ); disjoint groups are pushed apart after batch cola / fcose and during Animate; groups that share a member ( multi-membership, e. g. tags ) may overlap around the shared node.
the simulation is deterministic ( no randomness ) and converges slowly over tens of seconds, then sleeps; interactions wake it instead of restarting it.
dragging pins the held node while the sim keeps running around it; release rejoins the node at rest with no snap; clicks never disturb the sim.
cycling the Animate toggle pauses and resumes the same simulation state, so it converges to the same attractor as leaving it on.

view_controls

reqlan rq/extension/library/graph.rq

pan, zoom, and drag repositioning are supported on the canvas.
zoom range is wide rather than tightly capped so users can inspect fine detail or see the whole neighbourhood.
reframe_view fits and centres the camera on the graph bounding box without changing node positions or restarting layout / physics.
Zoom and Fit must continuously drive graph_label_auto opacity when Labels is in auto mode.

graph_labels

reqlan rq/extension/library/graph.rq

Graph node labels must show the full idea name without character truncation.
Wrapping is allowed; ellipsis truncation of display names is not.
Shared contract for Ideas Summary ( cytoscape ) and HTML export ( canvas ); surface-specific wiring lives under consumers.
graph_label_modes
graph_label_auto

Status: done

graph_label_modes

reqlan rq/extension/library/graph.rq

Every interactive graph should provide a Labels control that cycles auto ( default ), on, and off without changing graph membership.
On forces full opacity; off hides all labels; auto follows graph_label_auto.
Reset / default restore auto.
Ideas Summary: control in GraphControls.svelte, mode persisted via graph_ui_persistence.
HTML export: control in html-export-template.ts / html-export-assets.ts.
Driven by the same viewport zoom as view_controls.

Status: done

graph_label_auto

reqlan rq/extension/library/graph.rq

In Labels auto mode, visibility follows viewport zoom continuously rather than a hard cut.
Below a low zoom threshold labels are fully hidden; above a slightly higher threshold they are fully opaque; between those thresholds opacity ramps briefly through a muted / semi-transparent phase ( GRAPH_LABEL_FADE_START → GRAPH_LABEL_FADE_END ).
Hovered or dragged nodes remain fully opaque even when ambient auto opacity is low or zero.
Zoom and Fit from view_controls / reframe_view must update this opacity on each paint or zoom event.
Applies to Ideas Summary GraphCyController and HTML export canvas graph alike.

Status: done

graph_status_tag_filters

reqlan rq/extension/library/graph.rq

Status and tag graph filters are searchable checkbox dropdowns ( still a dropdown trigger; multi-select via checkboxes; OR within each field ).
They must distinguish attribute absence from an empty declaration and from a literal unspecified value:
- Not present — attribute key absent ( no `@status` / no `@tags` )
- Empty — attribute declared with no value ( `@status`, `@tags`, `@status ""`, bare flag )
- unspecified — literal authored value " unspecified "
Do not invent unspecified for missing attributes in rollups, clusters, or filter options.
Special options render differently from concrete values ( italic muted Not present; info-tint Empty; warning-tint unspecified ).
Shared helpers live in filter-specials.ts.
Surfaces: Ideas Summary SearchableCheckboxDropdown; HTML export SCD in html-export-assets.ts.

Status: done

reframe_view

reqlan rq/extension/library/graph.rq

Shared viewport behaviour for every surface that mounts GraphCyController ( Ideas Summary graph tab, activity bar mini graph, and future consumers ).
Implementation: reframeGraphToViewport and GraphCyController. reframeToViewport in graph-cy-controller.ts.
manual_reframe
auto_reframe
reframe_animation
Constants: GRAPH_VIEWPORT_PADDING ( 36 px padding around the element bounding box ), GRAPH_REFRAME_ANIMATION_MS ( 400 ms animated transition ).
Reframes resize the cytoscape container first, then fit all elements and centre the camera.
Does not clear selection, centreId, user-pinned drag positions, or live physics state — viewport only.

manual_reframe

reqlan rq/extension/library/graph.rq

Users can explicitly reframe the viewport when pan / zoom has moved the graph off-screen or they want to see the whole neighbourhood again.
- " Fit to view " control in GraphControls.svelte dispatches to GraphView → GraphCyController. reframeToViewport ( ).
- " Fit to view " control in MiniGraphCanvas.svelte calls the same API on the mini-graph controller.
Every graph surface that mounts GraphCyController should expose this control.

auto_reframe

reqlan rq/extension/library/graph.rq

The graph should automatically fit to the viewport when the loaded node set changes — without requiring the user to click " Fit to view ".
After each successful syncSlice, GraphCyController compares the sorted node-id set of the incoming slice with fittedNodeSetKey ( the set the viewport was last fitted to ).
When they differ, finishRender triggers an automatic reframe via reframeToViewport.
Triggers when any node is added or removed from the slice ( new neighbourhood, focus change, filter change that changes membership ).
Does not trigger for metadata-only updates on the same node ids ( label, colour, isCenter flag, etc. ) — those keep the user's current pan / zoom.
Does not trigger on requestLayout relayout when the node-id set is unchanged.

reframe_animation

reqlan rq/extension/library/graph.rq

The first reframe on a controller mount is instant ( synchronous cy. fit + cy. center ) so the graph appears immediately on first paint.
Every subsequent reframe — automatic ( auto_reframe ) or manual ( manual_reframe ) — animates pan and zoom smoothly over GRAPH_REFRAME_ANIMATION_MS using cytoscape. animate ( { fit, easing: ' ease-out-cubic ' } ).
Callers may pass `reframeToViewport({ animate: false })` to force an instant reframe.
Initial batch layouts use fit: false ( see graph_cytoscape ) so the controller owns the first fit and later animated handoffs are not double-applied.

layout_options

reqlan rq/extension/library/graph.rq

- user can select from a dropdown of layout options offered by cytoscape. js
- user can select whether to use compound layouts ( where compound basis is based on the folder structure )
- compound basis should be flexible and expected as an input

compound_graph

reqlan rq/extension/library/graph.rq

folder hierarchy is to be supported with compound layouts.

physics_options

reqlan rq/extension/library/graph.rq

- user can select from a dropdown of physics options offered by cytoscape. js
- the options for the physics should be exposed to the user in a menu too.
- user can select whether to use live physics / animation
- live physics uses the custom graph-physics simulation; cola remains selectable as a batch layout in the layout dropdown
- Ideas Summary exposes layout, live-physics, and force sliders in GraphControlPanel.svelte

current_file_pane

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Primary contextual pane when a. rq file is active. Sub-sections may collapse independently.
scope_pane
reference_lists_pane
parent_nodes_pane

scope_pane

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Composed context inspector per scope_pane_design.
Built from reqlan_context_model; not a flat file list.
See context_dimensions for workspace, current file, open files, file history, edit history, manual, and git lenses.
Git lens: git_history_lens ( history-first, not staging mirror ).
Legacy file-only fields live in current_file_context / currentFile slice when the current-file lens is expanded.
Implemented by ScopePane.svelte.

git_history_lens

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Expanded git dimension in scope_pane: focus-centric development history, not a Source Control duplicate.
Layout:
- Header: branch name, HEAD short hash, muted summary ( e. g. " main · 3 commits · 2 authors " ).
- Focus history ( primary ): up to ~ 8 commits touching the focus file / idea line range — relative time, short hash, subject, author.
Prefer `git log -L` for `.rq` ideas; fall back to path log. Non-. rq uses path `--follow`.
- Authors: compact chip row of top authors from that log window.
- Working tree ( secondary, collapsed by default ): dirty staged / unstaged paths for caution / footprint only.
Focus hero: history cue ( last commit age / branch ), not `git: staged|unstaged`.
Fingerprint Git axis and drilldown list commits / authors ( dirty paths secondary ) per fingerprint_axis_drilldown and tooltip_detail.
Aligns with git_context and development_history_signals.
Implemented by ScopePane.svelte ContextFingerprint.svelte.

Status: done

reference_lists_pane

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Actionable inbound and outbound reference lists for the focused idea.
- Inbound: ideas that reference the focus ( edges to the focus ).
- Outbound: ideas and files the focus references ( edges from the focus ).
- Group entries by edge kind ( dependency, related to, file ref, incompatible, etc. ) in collapsible sections.
- Show a short snippet or source line explaining why each edge exists where available.
- Text filter scoped to this pane only ( not the full ui-sql layer ).
- " Add to context " pins an idea into context_tray for Copilot / @ reqlan workflows.
- reference_resolution_parity: panel resolution must match the editor file view.
- unresolved_reference_create: unresolved idea targets get a create affordance, not a dead file link.
Implemented by ReferenceListsPane.svelte.

reference_resolution_parity

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Reference resolution for the activity-bar references pane must use the same shared rules as the editor
( document links / go-to-definition ), not a second ad-hoc classifier.
- Bare namespace-alias bracket refs such as `ActivityBarApp` that open a file in the editor must index as
resolved `file_reference` edges ( import path ), not unresolved idea refs — per import_namespace.
- Quoted file paths and markdown file links use the same file-target treatment as the language file-link resolver
in reqlan-file-link-resolver.ts /
reqlan-namespace-import-links.ts.
- File targets are opened relative to the defining `.rq` file ( same path join as the miniature graph ), not the workspace root.
- If a target resolves in the file view, it must resolve ( and be openable ) in reference_lists_pane.
Implemented by idea-extractor.ts,
file-reference-resolve.ts,
ReferenceListsPane.svelte.

Status: done

unresolved_reference_create

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

When an outbound reference remains unresolved after shared resolution ( missing idea, not a file / namespace-alias target ):
- Do * * not * * treat the label as a file path or navigate to a non-existent file.
- Show an unresolved badge and a * * + * * control with tooltip " Create idea ".
- Activating * * + * * opens create-idea ( reuse pallete_function_create_todo when available;
until then, the existing import-error create-file flow prefilled with the reference name and source document ).
Implemented by ReferenceListsPane.svelte and the activity-bar host message handler.

Status: done

parent_nodes_pane

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Upstream context for the focused idea.
- Ancestor chain as a breadcrumb with a configurable depth limit ( not only immediate parents ).
- Status rollup for ancestors ( e. g. counts by @ status ).
- " What blocks completion? " surfaces upstream ideas whose @ status is not done or in-progress.

selection_pane

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

When the user selects text spanning one or more `.rq` ideas ( context_selection ).
- List selected ideas with Focus and Pin actions.
- Contributes selection idea ids to context_footprint and may pair with graph_path_walk as path endpoints.
- Hidden when there is no non-empty multi-line selection overlapping ideas.

context_tray

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

A small pinned set of ideas carried across panes for AI context — the manual_context dimension.
- Chips for pinned ideas with remove control.
- " Clear tray " and " Copy tray as markdown " actions.
- Tray contents are included when invoking @ reqlan context or divide-and-conquer flows per divide_and_conquer.

context_panes_loading

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Ready panes: scope_pane, reference_lists_pane, and parent_nodes_pane show per-request loading and error, distinct from empty.

context_content_styling

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Pane bodies must not grow unbounded. Nested lists use NestedSection.svelte ( collapse + scroll ) under CollapsiblePane.svelte.
Priority: scope_pane; reference_lists_pane kind groups; also selection / parents.
ScopePane.svelte ReferenceListsPane.svelte

Status: done

tooltip_detail

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Scope pane tooltips are detailed enough to explain * what * a meter means and * why it matters *.
- scope_pane widgets ( stability, dependency pulse, timeline, churn, lens chips, footprint line ) expose granular hover copy on the control and its sub-items.
- ContextFingerprint.svelte has an ⓘ info button with semantic scoring help, per-axis hover copy, and fingerprint_axis_drilldown.
- Scoring copy is sourced from context_signals ( `CONTEXT_FINGERPRINT_HELP`, `CONTEXT_FINGERPRINT_AXIS_HELP`, `buildContextFingerprint` ) so UI stays aligned with context_fingerprint and ai_readiness_gauge.
Implemented by ContextFingerprint.svelte ScopePane.svelte.

Status: done

fingerprint_axis_drilldown

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

Each ContextFingerprint.svelte axis row ( Files, Requirements, History, Architecture, Git, Diagnostics, Coverage ) is clickable.
Clicking a row toggles a compact contributor table below it ( Source, Item, Detail ) listing what filled that axis — e. g. which lenses included a file, which ideas are in the footprint, git focus commits / authors ( dirty paths secondary ), anomalies, or relationship edges.
Table rows open / focus the related idea or file when actionable. Empty axes show a short “ why care / how to fill ” message.
Mirrors the interaction pattern of dependency_pulse_table. Aligns with context_fingerprint and tooltip_detail.
Implemented by ContextFingerprint.svelte ScopePane.svelte.

Status: done

dependency_pulse_table

reqlan rq/extension/module/activitybar-panels/current_context_scope.rq

The focus-hero DependencyPulse.svelte compass ( ↑ parents, → outbound, ← inbound, ↓ dependents, ● centre ) is clickable.
Clicking any arm or the centre toggles a compact reference table below with Dir, Role, Idea, and Status.
Rows open / focus the related idea. Duplicates of always-on inbound / outbound lists are omitted from the hero; the current-file lens still lists them.
Aligns with dependency_pulse.
Implemented by DependencyPulse.svelte ScopePane.svelte.

Status: done

miniature_graph_pane

reqlan rq/extension/module/activitybar-panels/minigraph.rq

A small interactive graph centred on the cursor idea ( or the file's first idea when the caret is outside any block ).
Consumes graph_library with sidebar-appropriate defaults; slices from local_graph_analysis.
- Default depth 1; + / - controls expand or collapse neighbourhood depth without opening Ideas Summary.
- Pan, zoom, and drag per view_controls.
- Labels default to graph_label_auto via shared GraphCyController ( no separate Labels control here; full control lives on graphical_graph ).
- manual_reframe — " Fit to view " in MiniGraphCanvas.svelte; same API as the full graph tab.
- auto_reframe and reframe_animation when the neighbourhood node set changes ( instant first fit, animated afterward ).
- No full layout / physics menus here ( defer to graphical_graph ).
- Single-click a node opens its source; double-click or " Focus " recentres the slice on that idea.
- Edge kinds styled like the full graph ( including dashed file-reference edges ).
- When nodes are truncated per node_truncation, show " + N more " with a control to open the centred slice in Ideas Summary.
- " Open in Graph tab " hands off centerId and query state to ideas-summary-panel.ts.
Mount cytoscape only while this sub-pane is visible per graph_cy_controller.

minigraph_file_reference_links

reqlan rq/extension/module/activitybar-panels/minigraph.rq

when the user clicks on a file reference link in the miniature graph, we should open the file in the editor
if the file is defined as relative, it should be opened relative to the defining file, not the workspace root
Fixed in local_graph_analysis: external file nodes now resolve their path against the defining file's folder ( via the edge source id ) when the slice is built, so a workspace-relative path is handed to the editor open action.

Status: done

minigraph_loading

reqlan rq/extension/module/activitybar-panels/minigraph.rq

Graph slice waits stay in miniature_graph_pane, not a second global overlay.
Show per-request loading and error, distinct from empty.

workspace_pane

reqlan rq/extension/module/activitybar-panels/workspace.rq

Multi-base index health, errors, and activity — without duplicating the full Index tab in index_panel.
- workspace_base_picker: choose the active base; do not render a full always-visible base list.
- For the selected base: state badge, sync progress ( processed / total + current file ), idea / edge counts, global and per-file errors, recent activity.
- Clickable file issue list opens the source location in the editor.
- Refresh / cancel in-flight sync / clear & rebuild for the selected base ( or all ); " Open index tab " hands off to ideas-summary-panel.ts with that base selected.
- When no bases exist: empty state with Create Base CTA ( create_base_onboarding ).
Non-blocking sync UX: nonblocking_index.
Implemented by WorkspacePane.svelte.

workspace_base_picker

reqlan rq/extension/module/activitybar-panels/workspace.rq

Bases in the Workspace pane are chosen via a * * searchable dropdown * *, not a stacked list of base rows.
- Closed: shows the active base label ( and compact ready / issue hint when useful ).
- Open: type-to-filter over discovered bases by label and path; selecting a match * * pins * * the active base ( active_base_switch ) — a pointer swap, not a sync.
- Options surface label / path plus ready state and idea / edge / issue counts so the user can distinguish bases before committing.
- Single-base workspaces still use the same control ( no special flat list ); empty discovery stays on the Create Base CTA.
- Prefer VS Code dropdown tokens for chrome; keep the control compact so health / stats / actions remain the focus of the pane.
Switch UX:
- Selecting a base posts immediately; the picker may flash * * Switching … * * until `indexHealth` confirms `activeBaseId` ( should be near-instant ).
- Never kick soft / hard sync on switch; readiness / progress for a not-yet-ready base is whatever the index already reports.
- Editor-follow must not overwrite a user-selected base on the same refresh that applies the selection.
Implemented by BasePicker.svelte in WorkspacePane.svelte; filter helpers in filter-bases.ts.

Status: done

workspace_loading

reqlan rq/extension/module/activitybar-panels/workspace.rq

Index sync progress belongs in workspace_pane; do not treat " index not ready " as a hard global error during cold start.
Host posts index health on view resolve and on `ready`; soft-waits when the index is not ready instead of erroring the whole bar.
Waiting for index: use workspace_pane sync progress affordance.

workspace_content_styling

reqlan rq/extension/module/activitybar-panels/workspace.rq

Pane bodies must not grow unbounded. Nested lists use NestedSection.svelte ( collapse + scroll ) under CollapsiblePane.svelte.
File → errors grouping via group-file-issues.ts in WorkspacePane.svelte.

Status: done

activity_bar

reqlan rq/extension/module/activitybar.rq

The extension should provide an activity bar sidebar for editor-adjacent requirement context per local_graph_view.
UI is implemented as Svelte webview panes per core.rq, not as a long-lived tree of static rows.
The host loads slices from the index via local_graph_analysis and forwards editor focus through activity-bar-webview-provider.ts and activity-bar-data-service.ts.
Panes should be performance conscious: capped neighbourhoods, lazy cytoscape mount, debounced cursor updates — same discipline as webview.
Workspace-wide tables, full layout controls, and unconstrained graph dumps belong in Ideas Summary per ideas_summary; panes link out with prefilled state instead of duplicating those views.

icon

reqlan rq/extension/module/activitybar.rq

the activity bar icon should use the reqlan logo. brand.rq

panes

reqlan rq/extension/module/activitybar.rq

- header_buttons
- current_file_pane
- selection_pane
- ideaset_pane
- file_references_pane
- recent_pane
- workspace_pane

header_buttons

reqlan rq/extension/module/activitybar.rq

Cross-pane controls live in a compact header above the pane stack.
- " Sync with editor " toggle: panes follow the active editor and cursor by default; when off, stay pinned on the last focused idea.
- hop_depth_control: global graph hop depth for context search, graph slice, references, and ancestors — not a boolean toggle.
- " Open in Ideas Summary ": reveal ideas-summary-panel.ts with the ideas table filtered to the current file, or the graph tab centred on the current idea.
- " Export slice ": JSON or CSV of the current neighbourhood only ( lighter than workspace export_JSON / export_csv ).
- " Copy as markdown ": copy the focused idea plus parents and reference lists for pasting into chat or PRs.
- Refresh control tied to index readiness.
- info_site_link

hop_depth_control

reqlan rq/extension/module/activitybar.rq

A * * − / value / + * * button pair ( not a 1 - hop / 2 - hop toggle ) sets global_hop_depth.
- Minimum hop depth is 1 ( direct neighbours only ); * * − * * is disabled at minimum.
- Maximum hop depth is capped ( default 4 for the activity bar ); * * + * * is disabled at maximum.
- Changing global depth rebuilds reqlan_context_model, refreshes graph / refs / ancestors panes, and updates context_footprint.
- When no effective_center_id exists, depth still updates session state; panes refresh when a centre appears.
- Legacy `setIncludeIndirect` maps to depth 2 / 1 for backward compatibility during migration.

info_site_link

reqlan rq/extension/module/activitybar.rq

The header shows an info control that opens the project site in the system browser.
Link id `site` from phonebook per activity_bar_site_link.
Resolved in the extension host via phonebook.ts ( canonical data in phonebook.json ), not hardcoded in the webview.
The webview receives the resolved label and href from activity-bar-webview-provider.ts and posts `openPhonebookLink` when the user activates the control.

current_file_pane

reqlan rq/extension/module/activitybar.rq

Primary contextual stack when a. rq file is active — details in current_file_pane.
Sub-panes: scope_pane, miniature_graph_pane, reference_lists_pane, parent_nodes_pane.

scope_pane

reqlan rq/extension/module/activitybar.rq

Composed context inspector — details in scope_pane.

git_history_lens

reqlan rq/extension/module/activitybar.rq

Focus-centric git history in the git lens — details in git_history_lens.

miniature_graph_pane

reqlan rq/extension/module/activitybar.rq

Small interactive neighbourhood graph — details in miniature_graph_pane.

reference_lists_pane

reqlan rq/extension/module/activitybar.rq

Inbound / outbound reference lists — details in reference_lists_pane.
Shared editor / panel resolution: reference_resolution_parity.
Unresolved idea create affordance: unresolved_reference_create.

refernce_lists_pane_reference_tiering

reqlan rq/extension/module/activitybar.rq

Inbound refernces may be direct, or via ideaset references.
The reference_lists_pane should tier the references based on the reference type. Design must keep in mind that that the ideaset refernces are likely more numerous and lower signal.

parent_nodes_pane

reqlan rq/extension/module/activitybar.rq

Upstream ancestor chain — details in parent_nodes_pane.

selection_pane

reqlan rq/extension/module/activitybar.rq

Multi-idea selection list — details in selection_pane.

ideaset_pane

reqlan rq/extension/module/activitybar.rq

When the focused idea belongs to one or more ideasets.
- List ideaset names with a dropdown of member chips ( same interaction model as idea_sets_tab ).
- Path column links to the ideaset source file.
- Hidden when the focus idea is not a member of any ideaset.

file_references_pane

reqlan rq/extension/module/activitybar.rq

File-scoped edges only — inbound and outbound file references for the focused idea.
Useful for tracing which source files implement or mention a requirement.
- Group shared file targets per referenced_files_grouping when multiple ideas reference the same path.
- Line-qualified references should navigate to the specific line when present.

recent_pane

reqlan rq/extension/module/activitybar.rq

Recently touched ideas in the session ( configurable count and truncation basis per node_truncation ).
- Click opens the idea; optional pin to context_tray.

workspace_pane

reqlan rq/extension/module/activitybar.rq

Workspace / multi-base index health and activity — details in workspace_pane.
Active bases chosen via searchable dropdown ( workspace_base_picker ); pane shows health for the selected base.
Empty discovery: create-base CTA per create_base_onboarding.

context_tray

reqlan rq/extension/module/activitybar.rq

Pinned ideas for AI context — details in context_tray.

performance

reqlan rq/extension/module/activitybar.rq

Sidebar webviews share the same constraints as webview_threading.
- The HTML / Svelte shell paints before index discovery begins; the post-paint `ready` handshake starts indexing.
- Keep sql. js outside the activation-critical host bundle and load it only when a database opens.
- Default neighbourhood slices; never load the full workspace graph into a pane.
- Debounce editor selection and cursor events before rebuilding slices.
- Lazy-mount cytoscape only for visible sub-panes; destroy when collapsed or hidden.
- Reuse local_graph_analysis and graph query builders rather than ad-hoc index walks in the webview.

Status: done

implementation_priority

reqlan rq/extension/module/activitybar.rq

Suggested build order:
1. scope_pane and reference_lists_pane ( index data only, no cytoscape ).
2. miniature_graph_pane with expand / collapse and handoff to Ideas Summary.
3. parent_nodes_pane with status rollup.
4. context_tray and create-stub integration with pallete_function_create_todo.
5. selection_pane, ideaset_pane, file_references_pane, recent_pane.

component_list

reqlan rq/extension/module/activitybar.rq

Priority release ( shipped ):
- Shell: App.svelte, HeaderBar ( includes info_site_link ), CollapsiblePane in activity-bar
- Panes: WorkspacePane, ScopePane, SelectionPane, ReferenceListsPane, MiniatureGraphPane, ParentNodesPane, ContextTray
- Graph: MiniGraphCanvas.svelte consuming shared graph lib per graph.rq
- Host: activity-bar-webview-provider.ts, activity-bar-data-service.ts, wire types in activity-bar-messages.ts
- HTML: get-activity-bar-html.ts
- Build: vite.config.ts → media / webviews / activity-bar /
Deferred ( not in priority release ):
- IdeasetPane, FileReferencesPane, RecentPane
- graph_path_walk UI pane
- ExportSliceButton
- Full workspace export via export_JSON / export_csv

minigraph_file_reference_links

reqlan rq/extension/module/activitybar.rq

File-ref click open behaviour — details in minigraph_file_reference_links.

Status: done

loading_state

reqlan rq/extension/module/activitybar.rq

After the activity bar shell mounts, the header may appear before pane data.
Cover every sequencing beat with an explicit loading or error affordance — never a blank content area:
1. HTML shell ( before Svelte boots ): inline waiting markup in get-activity-bar-html.ts.
2. Connecting: header visible; a post-first-frame `ready` handshake starts the index and requests the first host state.
3. Waiting for index: workspace_loading.
4. Ready panes: context_panes_loading and minigraph_loading.
Index sync progress belongs in workspace_pane; graph slice waits stay in miniature_graph_pane, not a second global overlay.
Host posts index health on `ready` and on subsequent status changes; soft-waits when the index is not ready instead of erroring the whole bar.

Status: done

panel_content_styling

reqlan rq/extension/module/activitybar.rq

Pane bodies must not grow unbounded. Nested lists use NestedSection.svelte ( collapse + scroll ) under CollapsiblePane.svelte.
Details: workspace_content_styling, context_content_styling.
WorkspacePane.svelte ScopePane.svelte ReferenceListsPane.svelte

Status: done

chat_participant

reqlan rq/extension/module/chat-participant.rq

the chat participant module should expose @ reqlan in vscode chat.
it should consume analysis functions from the analytical submodule rather than duplicating graph logic.
slash commands should use the rq- prefix only in chat, e. g. rq-search, rq-context, rq-graph, and rq-related for the active file.

chat_participant_completion

reqlan rq/extension/module/chat-participant.rq

file and requirement references should be code completed in the chat window via # file and # requirement language model tools.

mcp

reqlan rq/extension/module/chat-participant.rq

to support cursor / non-ms tools, this surface should be replicated / wrapped as an mcp server too.
the mcp package exposes the same analysis api as @ reqlan chat via stdio tools.
cursor project config lives in mcp.json and skills sync to skills via scripts / sync-cursor-ai. mjs.

chat_participant_skills

reqlan rq/extension/module/chat-participant.rq

the chat participant must not have duplicate skills.

context_scope_v2

reqlan rq/extension/module/context-scope-v2.rq

Evolves context_scope from a * * source-oriented * * model
( " where did this context come from? " ) to a * * decision-oriented * * model
( " what information helps a human or AI make the next decision? " ).
v1 context_dimensions remain valid * producers *
( workspace, current file, open files, file history, edit history, manual, git ).
v2 separates those producers from extracted signals, synthesized knowledge,
presentation views, and consumers — so new analyses can be added without
inventing new dimensions each time.
Primary UI principle: show_dont_tell — make project health, momentum,
relationships, and intent legible at a glance. Host fact chips
( " 17 modified files " ) remain useful; widgets below are the preferred
default for conveying meaning.
Surfaces: extend scope_pane / scope_pane_design,
Ideas Summary ( ideas_summary ), and graph overlays
( graphical_graph ) — same signals, different projections.

Status: in-progress

Tags: context, ui, knowledge, v2

context_model_layers

reqlan rq/extension/module/context-scope-v2.rq

Canonical v2 layers. Implementation builds on
reqlan_context_model; consumers must not reconstruct
project understanding independently.

Status: done

context_sources

reqlan rq/extension/module/context-scope-v2.rq

Stable raw producers. Answer: " Where are we collecting information from? "
Map from v1: workspace_context,
current_file_context, open_files_context,
file_history_context, edit_history_context,
manual_context, git_context become
sources ( and contributions ), not the whole model.
`workspace` = VS Code workspace chrome / ambient multi-base glance ( folder roots, discovery empty state ).
`base` = the active ontology ontology_base ( `.reqlan` - marked container ): its index, readiness, and path ( implied_context ).
Requirements graph and project index bind to the active base's store, not a merged workspace graph.

Status: incomplete

base_signals

reqlan rq/extension/module/context-scope-v2.rq

Multi-base facts for context_signals / synthesized_context:
active_base_id, active_base_root, active_base_ready, idea / edge counts for the active base,
sibling_bases ( id, path, ready, counts ), discovery_empty ( prompt create-base ).
Consumed by workspace_pane, Ideas Summary base switcher, and project_weather.

Status: in-progress

Tags: bases, multi-base

context_signals

reqlan rq/extension/module/context-scope-v2.rq

Extracted facts. Answer: " What useful information exists? "
One source may emit many signals ( e. g. git → development history, not only staged / unstaged ).
Families:
- requirement_signals
- file_signals
- development_history_signals
- project_activity_signals
- semantic_signals
- quality_signals
- user_signals
- relationship_signals
- temporal_signals
- risk_signals
- architecture_signals
- requirement_lifecycle_signals
- base_signals
Signals are evidence; synthesized_context merges them into actionable knowledge.

Status: done

requirement_signals

reqlan rq/extension/module/context-scope-v2.rq

related_requirements, parents, children, incoming / outgoing references,
linked implementation files, coverage status, requirement age, stability,
priority, verification state, orphaned, cycles, missing references.

file_signals

reqlan rq/extension/module/context-scope-v2.rq

active file, related files, recently viewed, recently edited, high churn,
frequently opened, ownership, generated / test / implementation /
specification / documentation classification.

development_history_signals

reqlan rq/extension/module/context-scope-v2.rq

Prefer actionable history over staged / unstaged alone.
development_context ( git reimagined ): current branch, active issue,
release version, commits, authors, change frequency / velocity, historical
and semantic hotspots, last meaningful modification, first introduction,
ownership concentration, refactor / merge likelihood, stability score.
First UI consumer beyond create / modify dates: git_context
/ git_history_lens —
focus commit trail and authors; working-tree staging demoted to secondary.

project_activity_signals

reqlan rq/extension/module/context-scope-v2.rq

currently changing subsystem, hot / cold modules, high activity area,
merge conflicts nearby, active branch, recent issue cluster,
recent requirement churn, release / milestone affected.

semantic_signals

reqlan rq/extension/module/context-scope-v2.rq

concept clusters, shared vocabulary, duplicate / near-duplicate /
similar requirements, contradictions, implicit dependencies,
missing abstraction, large / isolated concepts.

quality_signals

reqlan rq/extension/module/context-scope-v2.rq

missing documentation, large files / requirements, broken references,
failing diagnostics, lint / parse / test / build failures, coverage gaps.

user_signals

reqlan rq/extension/module/context-scope-v2.rq

manual pins, recent focus, navigation history, editing intent,
copied context, AI conversation history, last searched,
last graph traversal, frequently revisited.

relationship_signals

reqlan rq/extension/module/context-scope-v2.rq

—

temporal_signals

reqlan rq/extension/module/context-scope-v2.rq

Enables queries: what changed this week, why this requirement changed,
newly introduced risks, recent architectural evolution.

risk_signals

reqlan rq/extension/module/context-scope-v2.rq

—

architecture_signals

reqlan rq/extension/module/context-scope-v2.rq

—

requirement_lifecycle_signals

reqlan rq/extension/module/context-scope-v2.rq

—

synthesized_context

reqlan rq/extension/module/context-scope-v2.rq

Signals merged into decision-oriented knowledge not tied to a single source.
Example projection on a requirement:
- Importance, Confidence, Stability, Recent Activity
- Dependencies, Implementations, Tests, Documentation
- AI Risk
Synthesis powers show_dont_tell widgets and
ai_integration exports — preference for compact synthesized
facts over raw dimension dumps ( ai_context_export ).

Status: done

context_views

reqlan rq/extension/module/context-scope-v2.rq

Projections over the same signals — not separate data models.
Timeline · Graph · File · Requirement · Subsystem · Concept ·
Implementation · History · Risk · AI Summary.

Status: incomplete

context_consumers

reqlan rq/extension/module/context-scope-v2.rq

Shared semantic representation for: UI widgets, graph traversal,
AI agents, search, diagnostics, navigation-by-intent.
New analyses register as signal producers; consumers bind to signals /
synthesis, not to ad-hoc dimension lists.

Status: incomplete

show_dont_tell

reqlan rq/extension/module/context-scope-v2.rq

Make project state * * legible at a glance * *. Prefer visual evidence of
health, momentum, relationships, and intent over numeric fact lists.
Widgets below are show-don ' t-tell components for context_scope_v2;
each consumes context_signals / synthesized_context and may appear
in activity bar, Ideas Summary, focus heroes, search results, or graph overlays.
Placement guidance:
- Focus / card density: timeline_ribbon, churn_heat_bar, dependency_pulse,
stability_meter, change_velocity, requirement_lifecycle_wheel,
requirement_card, confidence_card, ai_readiness_gauge
- Workspace chrome / dashboard denser: activity_river, project_weather,
context_fingerprint, architectural_map
- Graph / Ideas Summary: hotspot_overlay, impact_radius,
activity_constellation, historical_replay_slider, relationship_cloud
- Coverage / ownership / density: knowledge_coverage, traceability_matrix,
ownership_distribution, concept_density, context_radar, semantic_diff_viewer

Status: in-progress

Tags: ui, widgets, show-dont-tell

timeline_ribbon

reqlan rq/extension/module/context-scope-v2.rq

Horizontal lifecycle ribbon for a requirement ( or focused entity ), not a single " last modified " label.
Show milestones along a line toward Now — e. g. created, first implementation,
last reviewed, current edit, last test — so maturity and recent activity
are visible in one glance.
Consumes requirement_lifecycle_signals and temporal_signals.
Fits scope_pane_design. focus_hero and requirement_card.

Status: incomplete

Tags: widget, timeline

churn_heat_bar

reqlan rq/extension/module/context-scope-v2.rq

Compact sparkline of edit intensity over time for a requirement, file,
folder, or subsystem ( e. g. ▁ ▁ ▂ ▁ ▁ ▇ █ ▆ ▂ ▁ ▁ ).
Hover reveals synthesized story ( stable / large rewrite / quiet since ).
Consumes development_history_signals and project_activity_signals.

Status: incomplete

Tags: widget, churn

dependency_pulse

reqlan rq/extension/module/context-scope-v2.rq

Spatial dependency summary instead of " Parents: 4 / Children: 12 ".
Compact compass ( ↑ parents, → children, ← siblings, ↓ dependents ) and / or
a filled * * Dependency Load * * bar showing centrality growth.
Consumes requirement_signals and relationship_signals.
Surfaced on focus hero and graph node details.
Click any arm or the centre toggles a reference table below the compass
( Dir / Role / Idea / Status ) per dependency_pulse_table.

Status: incomplete

Tags: widget, dependencies

stability_meter

reqlan rq/extension/module/context-scope-v2.rq

Segmented meter + percent ( e. g. Stable █ █ █ █ █ █ █ █ █ ░ 91 % ) derived from
edit frequency, age, dependency churn, and issue count — not raw git status.
AI and humans use it as a confidence cue for change. Pair with
confidence_card and risk_signals.

Status: incomplete

Tags: widget, stability

confidence_card

reqlan rq/extension/module/context-scope-v2.rq

Pre-edit checklist card: High / Medium / Low confidence with check / warn rows
( stable, reviewed, tested, high fanout, … ) and a confidence %.
Shown before AI modify workflows ( ai_integration ) and on
focus when synthesis is available.

Status: incomplete

Tags: widget, confidence, ai

activity_river

reqlan rq/extension/module/context-scope-v2.rq

Workspace-top ribbon of recent activity density ( yesterday / today bursts ).
Shows momentum, not a file list. Consumes project_activity_signals
and user_signals.

Status: incomplete

Tags: widget, activity

architectural_map

reqlan rq/extension/module/context-scope-v2.rq

Tiny layered minimap ( UI / Services / Core / Infra … ) with current focus
highlighted and bar width for effort concentration.
Consumes architecture_signals and project_activity_signals.
Links out to Ideas Summary graph rather than duplicating full layout.

Status: incomplete

Tags: widget, architecture

hotspot_overlay

reqlan rq/extension/module/context-scope-v2.rq

Graph-node encoding of churn / risk / discussion / instability
( size rings ○ ◎ ⬤ or green → red ). Same signal set as activity_constellation.
Applies to miniature_graph_pane and
graphical_graph.

Status: incomplete

Tags: widget, graph, hotspot

requirement_lifecycle_wheel

reqlan rq/extension/module/context-scope-v2.rq

Four-quadrant wheel: Specify · Implement · Test · Review.
Segments fill as evidence accumulates from requirement_lifecycle_signals
and quality_signals. Compact lifecycle for engineering projects.

Status: incomplete

Tags: widget, lifecycle

change_velocity

reqlan rq/extension/module/context-scope-v2.rq

Slow ↔ Fast bar from edits / week ( or equivalent ). Complements churn_heat_bar
( shape over time ) with a single magnitude readout.

Status: incomplete

Tags: widget, velocity

concept_density

reqlan rq/extension/module/context-scope-v2.rq

Per-folder or per-subsystem bars of conceptual richness
( Authentication █ █ █ █ █ █ █ █ █ █ vs Payments █ █ █ ).
Consumes semantic_signals; useful in Ideas Summary folders / index panel.

Status: incomplete

Tags: widget, semantic

knowledge_coverage

reqlan rq/extension/module/context-scope-v2.rq

Stacked coverage bars: Requirements / Implementation / Tests / Docs —
prefer filled bars over bare percentages. Consumes quality_signals
and requirement_signals. Pair with traceability_matrix.

Status: incomplete

Tags: widget, coverage

traceability_matrix

reqlan rq/extension/module/context-scope-v2.rq

Compact Req × Impl × Test ( and optional Docs ) check matrix for a local
neighbourhood or subsystem. Exposes gaps immediately.
Neighbourhood-scoped only — full-workspace matrices stay in Ideas Summary
with pagination / filters per ideas_summary.

Status: incomplete

Tags: widget, traceability

relationship_cloud

reqlan rq/extension/module/context-scope-v2.rq

Compact spatial alternative to a full graph: related concepts laid out by
semantic closeness ( distance encodes similarity ). Click focuses;
" Open in Graph " hands off to graphical_graph.
Consumes semantic_signals and relationship_signals.

Status: incomplete

Tags: widget, semantic, relationships

ownership_distribution

reqlan rq/extension/module/context-scope-v2.rq

Horizontal author share bars ( bus-factor at a glance ).
Consumes development_history_signals ownership and risk_signals
( e. g. single_contributor ).

Status: incomplete

Tags: widget, ownership

historical_replay_slider

reqlan rq/extension/module/context-scope-v2.rq

Time slider across the graph ( e. g. 2023 → Now ). Nodes and edges appear /
disappear; dependencies animate. Extremely powerful for architectural
storytelling; performance-capped neighbourhoods only in the activity bar;
fuller replay in Ideas Summary.
Consumes temporal_signals, requirement_lifecycle_signals,
relationship_signals.

Status: incomplete

Tags: widget, timeline, graph

requirement_card

reqlan rq/extension/module/context-scope-v2.rq

GitHub-issue-style compact card for search results and lists:
name, stability chip, meter %, last edited, ref / impl / test counts,
urgency flag ( e. g. recently changing ).
Composes stability_meter, churn_heat_bar, dependency_pulse
as optional rows — not all at once by default ( token / UI density ).

Status: incomplete

Tags: widget, card

context_radar

reqlan rq/extension/module/context-scope-v2.rq

Polar / radar chart of context richness axes ( Tests, Docs, Dependencies,
History, AI, … ). Filled polygon shows what the current
context_footprint actually covers.

Status: incomplete

Tags: widget, context

activity_constellation

reqlan rq/extension/module/context-scope-v2.rq

Spatial glow of nodes by activity ( GitHub-contribution feel, but layout-
aware ). Shows hotspots without a separate legend dump.
Complements hotspot_overlay; prefer one encoding per surface to avoid
competing visual channels.

Status: incomplete

Tags: widget, activity, graph

impact_radius

reqlan rq/extension/module/context-scope-v2.rq

On select / focus, fade in affected neighbours; opacity ∝ downstream impact.
Consumes relationship_signals and risk_signals. Works in miniature
graph and Ideas Summary graph.

Status: incomplete

Tags: widget, impact, graph

ai_readiness_gauge

reqlan rq/extension/module/context-scope-v2.rq

Ready-to-assist gauge: requirements ✓, implementation ✓, history ✓,
tests ✕, risk low — plus readiness %. Tells the user whether AI has enough
synthesized context before ai_add_to_context / export.
Pairs with context_fingerprint ( what is in context ) vs readiness
( is it enough / safe ).

Status: incomplete

Tags: widget, ai

semantic_diff_viewer

reqlan rq/extension/module/context-scope-v2.rq

Conceptual change summary instead of ( or above ) line diffs:
Added / Changed / Removed ideas or policies, plus impact count
( e. g. 17 requirements ). Higher signal for AI and review than textual diffs alone.
Consumes semantic_signals, relationship_signals,
development_history_signals.

Status: incomplete

Tags: widget, diff, semantic

project_weather

reqlan rq/extension/module/context-scope-v2.rq

Synthesized workspace health widget — the engineering " dashboard " glance:
Stable / Risk / Momentum / Knowledge / Recent Change, or compact meters
for Project Health, Momentum, Risk, Confidence.
Consumes synthesized_context across risk_signals,
project_activity_signals, quality_signals, and base_signals
( per-base readiness when multiple bases exist ). Belongs in activity bar
workspace lens / Ideas Summary index panel — not as competing hero noise
on every focus.

Status: incomplete

Tags: widget, dashboard, health

context_fingerprint

reqlan rq/extension/module/context-scope-v2.rq

Compact bars of what the current AI / composed context actually contains:
Files, Requirements, History, Architecture, Git, Diagnostics, Coverage.
Lets the user see expansion when LLM reports " context expanded "
( ai_context_export, ai_integration ).
Hover / info / drill-down affordances: tooltip_detail, fingerprint_axis_drilldown.

Status: incomplete

Tags: widget, context, ai

widget_composition_rules

reqlan rq/extension/module/context-scope-v2.rq

Show-don ' t-tell without dashboard clutter.

Status: incomplete

implementation_priority_v2

reqlan rq/extension/module/context-scope-v2.rq

After v1 implementation_priority is solid:
1. context_model_layers types: sources → signals → synthesis contracts
( extend analytical context model; keep v1 dimensions as sources ). ✓
2. Seed signal producers: development_history_signals,
requirement_lifecycle_signals, relationship_signals, risk_signals
from index + git ( reimagined, not staged / unstaged-only ). ✓ ( thin )
3. synthesized_context rollups for focus entity ( stability, confidence,
AI risk, coverage ). ✓
4. First widgets on focus hero: stability_meter, dependency_pulse,
timeline_ribbon, churn_heat_bar. ✓
5. requirement_card in search / Ideas Summary lists;
context_fingerprint + ai_readiness_gauge on AI context export. ✓
6. Graph overlays: hotspot_overlay, impact_radius. ✓
7. Workspace glance: project_weather, activity_river,
architectural_map. deferred
8. Deeper storytelling: historical_replay_slider, semantic_diff_viewer,
relationship_cloud, traceability_matrix. deferred

Status: in-progress

context_scope

reqlan rq/extension/module/context-scope.rq

Reqlan sidebar and AI workflows reason about a composed reqlan_context_model, not a single " current file " blob.
Context applies to * * any workspace file * *, not only `.rq` sources — see any_file_scope.
Context is built from orthogonal context_dimensions that the user can enable, pin, or collapse.
The activity bar scope_pane is the primary surface for inspecting and steering context; context_tray holds the manual_context dimension.
Token discipline per ai_integration: show summaries and counts by default; expand a dimension only on intent.
Parses per reference_wikilink.
Decision-oriented v2 ( sources → signals → synthesis → views → consumers ) and show-don ' t-tell widgets: context_scope_v2.

any_file_scope

reqlan rq/extension/module/context-scope.rq

The active editor may be a requirement file or implementation file ( Python, TypeScript, etc. ).
current_file_context must surface requirement links even when the file contains no block ideas.
Signals for non-. rq files ( and. rq files without a caret idea ):
- file_reference_links: `.rq` ideas whose outbound `file_reference` edges target this file path ( e. g. `apythonfile.py` ).
- folder_reference_links: `.rq` ideas whose `file_reference` targets a parent folder of this file.
- comment_reference_links: ideas resolved from `rq:…` tokens in this file's comments per references_in_functional_code_comments.
- git_context: focus-centric git history ( recent commits, authors, branch ); working-tree dirty badge secondary.
Focus behaviour:
- `.rq` file with caret in a block → idea focus ( unchanged ).
- Any file with linked requirements → file focus; effective_center_id defaults to the first linked requirement.
- No links → file focus with empty related lists; graph / refs panes stay idle until a requirement is focused.
Implementation: context-model.ts uses file-path-match.ts and `file_related_requirements` analyser; comment links are also resolved from live buffer text when indexed edges are absent.

file_reference_links

reqlan rq/extension/module/context-scope.rq

Matched when an indexed `file_reference` edge target resolves to the active file path ( exact or suffix match ).

folder_reference_links

reqlan rq/extension/module/context-scope.rq

Matched when an indexed `file_reference` edge target is a folder prefix of the active file per match_file_reference_target.

comment_reference_links

reqlan rq/extension/module/context-scope.rq

Matched from `comment_link` index edges and / or `rq:target` spans parsed from the active buffer.

context_dimensions

reqlan rq/extension/module/context-scope.rq

Seven dimensions contribute ideas and files to the effective context footprint.
Each dimension has a stable id, human label, default weight, and a one-line summary for collapsed UI.
- workspace workspace_context
Ambient VS Code workspace chrome and multi-base index glance: discovered bases, active base readiness / idea / edge counts — not a full graph dump. Distinct from the active base source in v2.
- current_file current_file_context
Active editor file. For `.rq`: caret idea, in-file outline, unresolved refs. For any file: any_file_scope links and git badge.
- open_files open_files_context
Other workspace editor tabs currently open ( any language ).
- file_history file_history_context
Session recency of visited workspace files ( navigation history ), distinct from edit history.
- edit_history edit_history_context
Session recency of edited workspace files and caret positions ( typing history ).
- manual manual_context
User-pinned ideas from context_tray and explicit " add to context " actions.
- git git_context
Focus-centric development history ( branch, recent commits, authors ) per git_information_capture; working-tree changes demoted.

reqlan_context_model

reqlan rq/extension/module/context-scope.rq

Canonical composed context per context-model.ts.
Implementation: context-model.ts.
- context_focus is the single anchor ( idea, file, selection, or none ).
- context_dimensions each contribute context_contribution records with counts and summary lines.
- context_footprint merges enabled dimensions into deduped idea / file sets and an effective_center_id for graph / refs panes.
- current_file_slice is the projection used when the current-file lens is expanded. Includes `isRqFile`, `referencingIdeas`, `commentLinkedIdeas`, `folderReferencingIdeas`, and optional `gitChange`.
- context_selection when the user highlights a non-empty range spanning one or more `.rq` ideas ( selection_pane ).
- global_hop_depth and dimension_hop_control overrides on the model.
Host increments `revision` when any dimension or hop depth changes; webview ignores stale posts by revision.

context_focus

reqlan rq/extension/module/context-scope.rq

kind: idea | file | selection | none.
When sync-with-editor is on, focus follows the caret idea in an active `.rq` editor, or file / selection context otherwise.
When pinned, focus stays on the pinned idea until cleared.
Selection focus applies when the user highlights text spanning one or more ideas ( selection_pane ).

context_selection

reqlan rq/extension/module/context-scope.rq

Union of ideas whose line ranges overlap the editor selection in a `.rq` file.
Drives selection_pane and contributes idea ids to context_footprint.

context_contribution

reqlan rq/extension/module/context-scope.rq

Per dimension: id, label, enabled, pinned, weight, ideaCount, fileCount, summary, hopDepth, supportsHopControl.
Disabled dimensions do not add to context_footprint but may still show a muted chip with zero count.
Pinned dimensions stay expanded in scope_pane_design until collapsed by the user.
Graph-searchable dimensions expose per-lens hop overrides via dimension_hop_control.

global_hop_depth

reqlan rq/extension/module/context-scope.rq

Session default hop depth ( 1 - 4 ) stored in context_session.
Drives graph slice expansion, reference list breadth, ancestor chain depth, and composed context export.
Surfaced in hop_depth_control and echoed on reqlan_context_model. globalHopDepth.

dimension_hop_control

reqlan rq/extension/module/context-scope.rq

When a graph-searchable dimension lens is expanded in scope_pane_design, show a local * * − / value / + * * pair.
Applies to current_file_context, open_files_context, file_history_context, edit_history_context, and manual_context — not workspace_context or git_context.
Per-dimension override inherits global_hop_depth until the user adjusts it; stored in dimensionHopDepth on the session and model.
Edge cases match hop_depth_control: disable − at min, + at max, clamp on apply.

context_footprint

reqlan rq/extension/module/context-scope.rq

Merged view across enabled dimensions.
- deduped idea ids and file uris with context_provenance ( which dimensions contributed each entry ).
- `summaryLine`: compact human text, e. g. " this file · 3 open · 2 git · 1 pinned ".
- `effectiveCenterId`: graph / refs / ancestors panes use this; defaults to focus idea, selection's first idea, first linked requirement for non-. rq files, else first idea in current file.

scope_pane_design

reqlan rq/extension/module/context-scope.rq

The scope pane uses a * * focus + lens * * layout — not seven stacked lists.
The experience should feel more like a wiki than a table: surfaced ideas, files, folders, commits, authors, and related context should prefer rich cross-links and drill-in navigation over flat tabular presentation.
Grouping should adapt to available context rather than staying fixed: file-heavy views may group by folder / path, development-history views may group by git recency / authorship / churn, and mixed views should choose the most explanatory structure for the current focus.

ai_context_export

reqlan rq/extension/module/context-scope.rq

header_buttons * * Context * * copies the composed reqlan_context_model as markdown: effective-centre requirement, non-. rq link sections, selection, pinned tray, and footprint summary.
ai_add_to_context should prefer the same composed context when the activity bar index is ready.

workspace_context

reqlan rq/extension/module/context-scope.rq

weight: 0. 1
Always on; contributes multi-base readiness and counts ( active base + sibling summary ) unless user opens workspace pane.
" Workspace " here means the VS Code workspace surface and ambient index health — not a single ontology base.
Active-base routing for focus / graph / refs follows implied_context; see context_sources `base`.

current_file_context

reqlan rq/extension/module/context-scope.rq

weight: 1. 0
Default enabled and expanded lens when a workspace file is active.

open_files_context

reqlan rq/extension/module/context-scope.rq

weight: 0. 6
Default enabled; summary lists tab count.

file_history_context

reqlan rq/extension/module/context-scope.rq

weight: 0. 4
Default enabled; capped list ( configurable, default 12 ).

edit_history_context

reqlan rq/extension/module/context-scope.rq

weight: 0. 5
Default enabled; capped list ( default 12 ); entries include last line touched.

manual_context

reqlan rq/extension/module/context-scope.rq

weight: 0. 9
Enabled when tray non-empty; pins override sync focus for effective_center_id when user chooses " focus pinned ".

git_context

reqlan rq/extension/module/context-scope.rq

weight: 0. 7
Should detect symbol lifecycle using symbol identity rather than line history for creation: who introduced the symbol, when it was introduced, who last meaningfully changed it, the total number of changes, and the relative change rate versus peer symbols.
Default enabled when repository detected.
Primary: focus-centric git history — branch, HEAD short hash, recent commits touching the focus file / idea, top authors.
Summary prefers history richness ( e. g. " main · 3 commits · 2 authors " ), not staged / unstaged counts.
Working-tree dirty files remain available as a demoted nested section and optional footprint contributors.
Focus hero shows a history cue ( last commit age / branch ) instead of a staged / unstaged chip.
Consumes git_information_capture and development_history_signals.
UI: git_history_lens.

implementation_priority

reqlan rq/extension/module/context-scope.rq

1. any_file_scope types and context-model.ts builder.
2. Host refresh for any workspace file; git / all-tab collection.
3. scope_pane_design non-. rq focus hero and grouped link panels.
4. context_selection + selection_pane.
5. Lazy `loadFileLens` for file-list dimensions.
6. ai_context_export.
7. graph_path_walk ( future pane / Ideas Summary handoff ).

graph_path_walk

reqlan rq/extension/module/graph-path.rq

Future capability: walk the requirement graph * * point-to-point * * between two chosen ideas.
Complements the activity bar's single-centre neighbourhood ( miniature_graph_pane ) and Ideas Summary's unconstrained graph tab ( graphical_graph ).

problem

reqlan rq/extension/module/graph-path.rq

Users often need to answer: " How does requirement A relate to requirement B? " — not the full ego-graph around A, and not an unbounded workspace dump.
Today they manually expand hops or search references. A dedicated path walk would make dependency chains, impact routes, and gap analysis inspectable in the sidebar or graph tab.

path_query

reqlan rq/extension/module/graph-path.rq

Inputs:
- `fromIdeaId` ( source node )
- `toIdeaId` ( target node )
- optional `maxDepth` ( default 8 )
- optional `edgeKinds` filter ( references, file_reference, incompatible, … )
- optional `direction` ( undirected default, or outbound-only / inbound-only for directed traces )
Output: path_result — zero or more shortest paths through the indexed graph, capped for token and UI limits.

path_result

reqlan rq/extension/module/graph-path.rq

- `found`: boolean
- `paths`: ordered list of graph_path ( typically top 1 – 3 shortest )
- `truncated`: true when search hit depth or branch limits
- `summaryLine`: e. g. " A → implements → B → depends on → C " for collapsed UI

graph_path

reqlan rq/extension/module/graph-path.rq

Ordered nodes and edges from source to target.
Each step records idea id, name, status, edge kind, and optional snippet / line for the traversed edge.
Paths with unresolved hops are marked broken; UI offers jump-to-source like reference_lists_pane.

path_ui_design

reqlan rq/extension/module/graph-path.rq

Entry points:
- Activity bar: " Path to … " on focus hero when a second idea is pinned or selected ( manual_context + selection_pane ).
- Ideas Summary graph tab: shift-click two nodes to set endpoints.
- Command palette: `Reqlan: Find path between requirements`.
Presentation ( sidebar-first ):
- Collapsed: summaryLine under the scope footprint line.
- Expanded: vertical stepper ( breadcrumb ) with edge kind labels; optional overlay on graph_library highlighting only path edges / nodes.
- When no path: show closest partial path or " no connection within N hops " with expand-in-Summary action.
Performance:
- BFS / bidirectional BFS on sqlite edge tables via local_graph_analysis — never materialise full workspace graph.
- Debounce endpoint changes; cache last path per `(from,to,depth)` revision tied to index catalog generation.

relationship_to_context

reqlan rq/extension/module/graph-path.rq

Path endpoints should default from context_focus and effective_center_id.
A successful walk contributes traversed idea ids to a transient " path context " slice suitable for ai_context_export without pinning every intermediate node.

implementation_notes

reqlan rq/extension/module/graph-path.rq

Analytical: add `findPathsBetween(store, fromId, toId, options)` returning path_result.
Wire: new `loadGraphPath` message alongside existing `loadGraph` / `loadAncestors`.
UI: defer dedicated pane until selection_pane and composed context are stable; prototype in Ideas Summary graph tab first.

ideas_summary_base_scope

reqlan rq/extension/module/ideas_summary/base-scope.rq

Ideas Summary is scoped to one base at a time.
- Active base defaults to the longest-matching base root for the focused editor ( implied_context ).
- Chrome includes an explicit base switcher; Overview, Bases, Ideas, Ideasets, Attributes, References, Graph, Timeline, and Index tabs bind to the selected base's index only ( Bases lists all discovered bases; Index is last ).
- Switching base is a pointer swap ( active_base_switch ): pin via `setActiveBaseId`, rebind status / tables / graph UI immediately — do not await sync on the switch call; not-ready bases get fire-and-forget open + soft-sync catch-up.
- Graph UI persistence is per-base: workspaceState key `reqlan.ideasSummary.graphUi.<baseId>` via graph-ui-state.ts.
- Activity bar " Open in Ideas Summary " passes the current active base id into ideas-summary-panel.ts.
- No merged cross-base tables or graphs in this pass ( multi_base_environment ).

Status: done

Tags: bases, ideas-summary, multi-base

graphical_graph

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

There should be a tab that renders requirement ideas and references as a force-directed web.
The graph tab lives in the Ideas Summary webview per ideas_summary.
UI is implemented in GraphView.svelte.
Graph slices are built in webview-graph-queries.ts and served by ideas-summary-panel.ts.
By default the view focuses on the active editor file's first idea; without a focus it shows a capped slice of matching ideas rather than dumping the full graph.
Users can filter by search text, path, multi-select @ status, and multi-select tags per graph_status_tag_filters.
An " Indirect references " toggle expands neighbourhood depth from 1 to 2 hops.
Clicking a node opens its source; double-click or " Focus graph " recenters the slice on that idea.
External file references render as dashed edges to file nodes.
A toggleable key explains node colours and edge styles and toggles node-type visibility per key_panel_toggle; a toggleable control_panel exposes layout, physics, and node-budget settings. Key and Controls state persist per workspace via graph_ui_persistence.
Pan, zoom, and drag repositioning per view_controls.
manual_reframe via " Fit to view " in ui_controls; auto_reframe when the loaded node set changes; reframe_animation for smooth transitions after the first paint.
Node text labels per graph_labels, graph_label_modes, and graph_label_auto.
Layout, compound grouping, and live physics behaviour per layout_physics, layout_options, physics_options, and compound_graph.
Cytoscape lifecycle and threading constraints per graph_cy_controller and webview_threading.

library

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

should consume the graph_library

root

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

GraphView.svelte

ui_controls

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

Controls live in GraphControls.svelte and dispatch events to GraphView.
manual_reframe — " Fit to view " calls GraphCyController. reframeToViewport per reframe_view.
auto_reframe and reframe_animation are handled by the shared controller; no extra UI beyond pan / zoom / drag.
Labels control cycles graph_label_modes ( auto / on / off ) and applies graph_label_auto via GraphCyController. setLabelMode.
Status and tag filters are multi-select dropdowns per graph_status_tag_filters.
The Key button toggles a draggable legend panel in GraphKeyPanel.svelte over the graph canvas.
The Controls button toggles control_panel.
Overlay panels ( Key and Controls ) are siblings of the cytoscape mount inside a graph-surface-wrap — never children of the cy container — so native form controls receive pointer events.

graph_loading

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

the extension pushes graphSlice when the index is ready — no empty waitingForIndex wedge.
ideas-summary-panel.ts sets graphSlicePending on loadGraph and delivers the slice when the index becomes ready ( including via index status updates ).
Index status posts must not await graph slice builds, so sync progress keeps updating the Index tab.
webview state in app.svelte.ts is query, slice, loading, rendering, and error only.
App. init attaches the window message listener during App. svelte script setup ( before child onMount ) so loadGraph replies are never dropped.
GraphView marks a slice as synced only in onRendered ( after cytoscape flush + layout ), not before syncSlice is queued.
Webview → extension posts go through vscode.ts which JSON-clones payloads so Svelte $ state proxies are structured-clone safe.
GraphView remount reuses app. graph. slice when present; it only loadGraphs when there is no slice and nothing in flight, or force-retries after an error.
GraphView mounts only while the graph tab is active ( see TabPanels ); per graph_cy_controller do not keep cytoscape alive under display: none.

node_truncation

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

nodes are truncated if there are too many.
the count should be configurable; as should the truncation basis ( last changed.., last accessed.., owned by etc. )
Max nodes and keep-by basis are edited in control_panel; query fields are maxNodes and truncationBasis on GraphViewQuery.
Default budget is GRAPH_MAX_NODES ( 120 ); hard ceiling is GRAPH_NODES_HARD_CAP ( 1000 ) in webview-graph-queries.ts — raise that constant to lift the cap.
Supported bases today: path, git-modified, git-created ( git timestamps from the index ). Last-accessed / owned-by need index fields before UI can offer them.

referenced_files_grouping

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

referenced_files should be grouped into a common node if they're referenced by multiple ideas.
Line numbers should be treated like ideas if specified, such that the reference points to items in rendered graph.

cola_vs_phyics

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

the user should have a constraint based layout; and a physics based layout; and some other options.

key_and_controls

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

there is a toggle that open a key; and a toggle that opens a control_panel.

control_panel

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

Floating panel in GraphControlPanel.svelte, toggled from ui_controls.
Provides layout algorithm selection, live-physics toggle, compound grouping, physics force sliders, max node count, and truncation basis.
Physics tunables call GraphCyController. setPhysicsSettings; node budget changes re-request the graph slice via loadGraph.
Mounted as a sibling of the cytoscape container ( not inside it ) so range sliders and selects work with native browser events.
When positioned, a ResizeObserver on the surface wrap reclamps panelX / panelY so the panel stays fully inside after the webview is resized; Key panel uses the same reclamp.
Open / closed state and all control values persist per graph_ui_persistence.

key_panel_toggle

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

the key panel should be able to toggle inclusion / visibility of the different node types.
Node-type rows in GraphKeyPanel.svelte are toggle buttons; hidden types render dimmed with a struck-through label.
Toggleable types are block, one-liner, ideaset, focused idea, and external file — GraphNodeTypeId in graph-theme.ts, classified per node by graphNodeTypeId ( same priority as node fill colour ).
GraphView tracks hidden types and calls GraphCyController. setHiddenNodeTypes in graph-cy-controller.ts, which flags matching nodes with data typeHidden; a display: none stylesheet rule in graph-cytoscape.ts hides them, and cytoscape hides edges whose endpoint is hidden.
Compound containers whose members are all hidden are hidden too. Hiding is client-side visibility only: the slice still contains the nodes, node / edge counts are unchanged, and flags reapply after every slice sync.
Key open state and hidden node types persist per graph_ui_persistence.

graph_ui_persistence

reqlan rq/extension/module/ideas_summary/graphical_graph.rq

Key and Controls state is stored in VS Code ExtensionContext. workspaceState under key GRAPH_UI_WORKSPACE_STATE_KEY ( reqlan. ideasSummary. graphUi ).
Shape and normalisation live in graph-ui-state.ts; the host reads / writes it from ideas-summary-panel.ts.
On webview ready the extension posts graphUiState; the webview posts persistGraphUiState ( debounced ) whenever AppState. patchGraphUi runs in app.svelte.ts.
Persisted fields: showKey, showControls, hiddenNodeTypes, layoutId, useCompound, compoundBasisId, animatePhysics, labelMode, maxNodes, truncationBasis, and the five physics sliders ( gravity, repulsion, linkStrength, linkDistance, damping ).
GraphView in GraphView.svelte treats app. graph. ui as the source of truth and applies layout / physics / hidden types / label mode to GraphCyController when those fields change.
The first graph load waits for graphUiState so restored node budget is included in loadGraph.

ideas_summary

reqlan rq/extension/module/ideas_summary/webview.rq

The Ideas Summary webview is a workspace-wide page for tables ( and graph ) summarising ideas
per simple_views and webview.
Tabs align with salient ontology.rq data and HTML export list views ( html_export_list_views ):
ontology_aligned_tabs.
It should be performance conscious and avoid full-graph dumps unless requested by the user.
It should be paginated.
It should be filterable and sortable via a ui-sql layer per table_column_filters and table_column_options.
Webview UI is implemented with Svelte per core.rq
the extension host loads compiled assets from ideas-summary
table queries are built in webview-table-queries.ts
the extension host forwards query state through ideas-summary-panel.ts
Ideas Summary chrome should include a link that opens export_webview.
Multi-base scope and switcher: ideas_summary_base_scope.

ontology_aligned_tabs

reqlan rq/extension/module/ideas_summary/webview.rq

Tab order: Overview, Bases, Ideas, Ideasets, Attributes, References, Graph, Timeline, Index.
Index is last — workspace index health and maintenance, not the primary browsing surface.
Covers base, idea, ideaset, attribute, reference,
the graph cartography tab, and timeline_page; Overview mirrors HTML export home metrics lightly.
Files / clusters / print families stay export-only for now.

pages

reqlan rq/extension/module/ideas_summary/webview.rq

- ideas summary ideas-summary-panel.ts
- header / status chrome with base switcher and link to export_webview
- overview_page OverviewPanel.svelte
- bases_tab BasesTable.svelte
- ideas list IdeasTable.svelte
- filterable and sortable via TableToolbar.svelte, ColumnFilterRow.svelte, and SortableTh.svelte
- column show / hide via TableOptionsMenu.svelte / table_column_options
- groupable by idea kind ( block / oneliner ) per group_by_type
- other attributes shown as expandable chips per ChipList.svelte
- clicking an attribute chip adds a column, filters to ideas with a non-null value for that attribute, and sorts by it ( combinable with other filters )
- references split into outbound and inbound chip columns with counts
- clicking a reference chip filters ideas that share that edge ( combinable with other filters )
- block idea bodies shown in a scrollable cell per IdeaBodyCell.svelte
- ideasets IdeasetsTable.svelte / idea_sets_tab
- filterable and sortable via ui-sql layer; column filters and options
- attributes_tab AttributesTable.svelte
- references ReferencesTable.svelte
- filterable and sortable via ui-sql layer; groupable by reference type per group_by_type
- Graph view: see graphical_graph
- timeline_page TimelinePanel.svelte
- index_panel IndexPanel.svelte ( last tab — index health )

overview_page

reqlan rq/extension/module/ideas_summary/webview.rq

First tab: a workspace overview for the active base — product-facing copy ( not index / debug jargon ).
- At a glance: idea count, reference count, issues, bases, and a friendly readiness status.
- Coverage: collapsible overview_coverage_scores ( lazy, non-blocking ).
- Search: live cross-surface search over ideas, ideasets, attributes, and references for the active base;
results group by surface with sample hits and actions to open the matching tab with the query applied ( overview_search ).
- Export: buttons that open export functionality — Export form / HTML, and PDF ( export_webview, features-export.rq pdf path ).
- Links: project site, support / email, GitHub.
- Recent changes preview ( idea names when available ) with a link to timeline_page.

overview_coverage_scores

reqlan rq/extension/module/ideas_summary/webview.rq

Collapsible " Coverage " section on overview_page / OverviewPanel.svelte.
Product-facing metrics for how thoroughly ideas map into the active base's project files
( respecting configuration_rqignore ):
- Linked files: percent of project files ( non-requirement, non-ignored ) that ideas reference —
exact path match after resolve, or under a referenced folder. Show " N of M project files ".
- Requirement density: ideas per thousand lines of eligible project code; also show idea count and line count.
- Linked paths: distinct files or folders referenced from ideas.
- Requirement files: count of requirement documents in the base.
Collapsed by default. Calculate only when the user expands the section ( not on Overview open / tab switch ).
Non-blocking: host work must not stall Overview chrome or other tabs; show a loading state until the result arrives.
When the index is not ready or calculation fails, show a clear message — never fake zero scores.
Recalculate on expand when the active base changes or when the user refreshes; otherwise reuse the last result for the session.

Status: done

Tags: overview, coverage, metrics

overview_search

reqlan rq/extension/module/ideas_summary/webview.rq

Overview search fans out across Ideas, Ideasets, Attributes, and References using the same ui-sql filters as those tabs.
Debounced; returns counts plus a short sample of hits per surface; clicking a hit opens the idea ( or the attribute → Ideas handoff );
" Open in … " applies the search string on that tab.

timeline_page

reqlan rq/extension/module/ideas_summary/webview.rq

Timeline tab shows the evolution of ideas for the active base — not raw file-index noise.
Sources:
- Git idea lifecycle from indexed `git_created_at` / `git_modified_at` ( created + last edited as separate events when they differ )
- Session idea reindex activity ( one event per idea persisted, with name / status / summary when available )
Opening the tab backfills missing git dates via the `git_dates` analyser ( capped batch ) so the feed is useful without visiting every idea in the Activity Bar.
Reindex must preserve existing git dates across upsert.
Entries are reverse-chronological, filterable by source ( git / reindexed ), and clickable to open the idea.
Each event surfaces idea-centric info: name, short summary, status, kind / tags, and path.
Full live multi-commit git log browsing remains out of scope; this surfaces indexed idea history first.

Status: done

Tags: timeline, ideas, git

bases_tab

reqlan rq/extension/module/ideas_summary/webview.rq

Table of discovered base entries in the workspace ( label, path, ready, idea / edge / issue counts, state ).
Selecting a row pins that base ( pointer swap ) per ideas_summary_base_scope.
Filterable / sortable / column options like other tables; data comes from index status, not a merged cross-base SQLite dump.
Client-side search and column filters via BasesTable.svelte / bases-filter matcher.

Status: done

attributes_tab

reqlan rq/extension/module/ideas_summary/webview.rq

Attributes index for the active base, aligned with html_export_attributes_index:
attribute key, idea count, distinct value count, sample values.
Searchable and filterable; clicking a key opens Ideas with that attribute column enabled.
Aggregated in webview-table-queries.ts / sqlite store.

idea_sets_tab

reqlan rq/extension/module/ideas_summary/webview.rq

The idea sets page should list the ideasets
unlike the ideas page, it should not directly to the ideaset, but should have a dropdown to it's items.
the path column should link to the ideaset source.
members should appear as chips with a … control to expand and show all member chips when needed.
per IdeasetsTable.svelte

table_column_filters

reqlan rq/extension/module/ideas_summary/webview.rq

Every data table supports a global search and a per-column filter row ( ColumnFilterRow.svelte ),
matching the usability of html_export_list_views.
Text / path / body columns use searchable inputs; closed sets ( idea kind, reference type, ideaset kind, base ready )
use select / multi-select from a fixed option list.
Column filters are applied in the ui-sql layer ( webview-table-queries.ts ) together with existing chip filters.
Table panels must bind AppState query / rows via Svelte 5 `$derived` ( not legacy `$:` ) so filtered results from
the extension message listener re-render — same pattern as graphical_graph / GraphView.
Bases table filters client-side in the webview; other tables round-trip search through ideas-summary-panel.ts.

Status: done

table_column_options

reqlan rq/extension/module/ideas_summary/webview.rq

Each table has an Options control ( TableOptionsMenu.svelte ) to show or hide columns.
Visibility persists per tab in workspaceState via table-ui-state.ts.

group_by_type

reqlan rq/extension/module/ideas_summary/webview.rq

Ideas table can group by idea kind ( block / oneliner ).
References table can group by reference type ( file / comment / sub-idea ).
Grouping is a toolbar toggle; rows are ordered by group then the active sort; UI shows collapsible group headers.

index_panel

reqlan rq/extension/module/ideas_summary/webview.rq

Last tab: workspace index health — readiness, summary stats, sync progress, errors, refresh / cancel / clear-and-rebuild.
per idea_index_triggers and nonblocking_index
Implemented by IndexPanel.svelte.

index_panel_base_support

reqlan rq/extension/module/ideas_summary/webview.rq

The index_panel / Ideas Summary chrome supports switching between bases in the workspace.
Switch is a pointer swap per active_base_switch and ideas_summary_base_scope — rebind views, do not sync.

Status: done

ideas_table_filters

reqlan rq/extension/module/ideas_summary/webview.rq

the ideas table should support text search, column sorting, and attribute-column filters driven by chip clicks.
attribute filters require a non-null attribute value in sqlite json per webview-table-queries.ts
reference chip filters match outbound / inbound edges by target or source id per webview-table-queries.ts
chips are right-aligned so truncated labels keep the informative suffix visible.
active attribute and reference filters appear as removable chips in the table toolbar.
Also table_column_filters, table_column_options, and group_by_type.

Status: done

graphical_graph_tab

reqlan rq/extension/module/ideas_summary/webview.rq

see graphical_graph

application_memory

reqlan rq/extension/module/index.rq

Base-local application memory for reqlan tools lives under `<base>/.reqlan/`.
The presence of `.reqlan` * * marks * * a directory as a base; each base owns its own store.
Shared by the VS Code extension, cli_package, and MCP ( server.ts ) — not VS Code `globalStorageUri` / extension-private storage.
The ideas graph index ( index_ideas / index_technology ) persists as `ideas-index.sqlite` inside that directory.
Index timing diagnostics persist separately as `index-diagnostics.sqlite` ( index_diagnostics_store / index_diagnostics ) so rebuilds of the ideas index do not wipe history.
Export form defaults ( all formats via export_webview, including HTML options in html_export_form ) persist as `export_settings.json` in the same directory ( active base ).
Path ignore rules live as `.rqignore` in the same directory ( rqignore / configuration_rqignore ).
Path resolution is owned by application-memory.ts ( `resolveApplicationMemoryPath` ); consumers must use it ( or `REQLAN_INDEX_PATH` override for a single store ) so tools read and write the same store for a given base.
Multi-base discovery / registry: multi_base_environment. Index engine ownership: ownership. Extension wiring: index.ts.
Aligns with function_parity: shared analytical memory, not host-only state.

Status: done

index_diagnostics_store

reqlan rq/extension/module/index.rq

Per-base diagnostic timing index at `<base>/.reqlan/index-diagnostics.sqlite`.
Sibling of `ideas-index.sqlite`; not deleted by Clear & rebuild.
Records sync runs and per-file durations for index_diagnostics_metrics.
Webview: index_diagnostics_webview.

Status: done

rqignore

reqlan rq/extension/module/index.rq

`.reqlan/.rqignore` filters which paths discovery and indexing crawl, using gitignore syntax relative to the base root.
Owned by rqignore.ts in `@reqlan/analytical` so CLI and editor share behaviour.
Defaults cover `node_modules/`, virtualenvs, build dirs, VCS / editor stores, database files ( `*.db3`, sqlite ), secrets, and hidden entries; new bases seed the file via create-base.
Product configuration statement: configuration_rqignore.

Status: done

idea_index_triggers

reqlan rq/extension/module/index.rq

Refresh automatically on `.rq` file change via watchers ( indexing_trigger_filesave ).
Idle: cheap background staleness check — indexing_trigger_auto.

git_information_capture

reqlan rq/extension/module/index.rq

Capture and surface git development history for requirements and files — not only working-tree staging status.
On-demand / index-accessible:
- ownership and top authors ( name; email when available )
- creator ( first introduction ) and last meaningful modification
- edit frequency / commit count for the focus path or idea line range
- recent commit trail ( subject, author, authoredAt, short hash ) for the git_context lens
Future: adjacency score from edit state and frequency of neighbours.
Feeds development_history_signals and git_history_lens.

webview

reqlan rq/extension/module/webview.rq

Extension webviews are Svelte UIs hosted by the VS Code extension per core.rq.
They should be performance conscious: prefer capped, paginated, or scoped slices and avoid full-graph dumps unless the user explicitly requests one.
The extension host loads compiled assets from `packages/extension/media/webviews/`.
Webview modules in the extension:
- Ideas Summary — overview, ontology tables ( bases / ideas / ideasets / attributes / references ), graph, and index ( last ): ideas_summary / ideas_summary / ontology_aligned_tabs
- Activity bar — editor-adjacent sidebar panes: activity_bar
- Export form — multi-format graph export: export_webview
- Onboarding — first-install / welcome webview: installation_event

installation_event

reqlan rq/extension/onboarding/page-thanks-for-installing.rq

On installation of the extension a webview should be opened showing:
- A welcome message
- Resolved links to site, github, docs etc. ( not template placeholders )
- A syntax-highlighted example `.rq` with real URLs ( clickable ) from thanks-for-installing.template.rq after placeholder substitution
- A control to open that example as an untitled `.rq` editor beside the webview
- Short tips for the activity bar and `@reqlan` chat
- A thanks to sponsors
Place in overall install sequencing: welcome_webview_install / extension_installation.
Implemented as a Svelte webview under onboarding bundled to onboarding and opened once on first activation by open-thanks-for-installing.ts via onboarding-panel.ts.
Resource links and template values are resolved at runtime from phonebook through phonebook.ts and posted to the webview; the example block imports thanks-for-installing.template.rq via Vite `?raw` and substitutes `{{…}}` placeholders before display.
Highlighting uses the onboarding tokenizer in rq-highlight.ts.
The source template still uses placeholders such as { { SITE_URL } }; those matching braces are body prose per nested_curly_braces and must parse without errors.
Activation state is stored in extension global state key `onboarding` with `onboardingMessageShown` and `lastVersion` per onboarding-state.ts.
VS Code persists `globalState` in the extension global storage directory ( `globalStorage/reqlan.reqlan-extension/state.vscdb` under the editor user data folder ).

Status: done

show_onboarding_command

reqlan rq/extension/onboarding/page-thanks-for-installing.rq

A command_palette action should reopen the onboarding webview on demand.
Command: Show Onboarding ( category Reqlan, id `reqlan.showOnboarding` ).
Implemented by register-onboarding-commands.ts calling open_onboarding_page.
Does not reset onboarding_state.

Status: done

open_onboarding_page

reqlan rq/extension/onboarding/page-thanks-for-installing.rq

Opens the onboarding webview panel ( `reqlan.onboarding` ) via open-thanks-for-installing.ts and onboarding-panel.ts.

onboarding_state

reqlan rq/extension/onboarding/page-thanks-for-installing.rq

Onboarding persistence uses VS Code `ExtensionContext.globalState` under key `onboarding` in onboarding-state.ts.
Fields: `onboardingMessageShown`, `lastVersion`.

installation_event_trigger

reqlan rq/extension/onboarding/page-thanks-for-installing.rq

The installation event should be checked and triggered at extension activation.
Verified: main.ts calls `openThanksForInstallingIfNeeded` at the end of `activate`, and onboarding_check documents the gating behaviour.

Status: done

refactor_changes

reqlan rq/extension/refactor_support.rq

On rename, move, or delete of files or symbols, the extension should update the
idea index, import statements, embedded file references, comment references, and
other idea references that are affected.
The index should be resilient to duplication, particularly when ideas move between files:
the old hosting file URI must be cleared before or when the destination is reindexed.
refactor_file_moves refactor_symbol_rename refactor_symbol_move refactor_symbol_delete
Implemented by workspace-index.ts, index-service.ts, reqlan-idea-refactor.ts, and register-file-mutation-hooks.ts.

refactor_file_moves

reqlan rq/extension/refactor_support.rq

The extension should watch for file moves and renames, migrate the index for moved
. rq files, and update imports and path references both inside the moved file ( outbound )
and in other files that pointed at it ( inbound ), including comment paths in code files.
There should be a single prompt per batch asking whether to apply path updates,
aligned with move_file and rename_file.
Implemented by register-file-mutation-hooks.ts, file-move-plan.ts, file-mutation-gate.ts, file-path-rewrite.ts, and reqlan-path-references.ts.

refactor_symbol_rename

reqlan rq/extension/refactor_support.rq

Syntactic symbols ( ideas, ideasets, import aliases, and import paths ) should be
renamable via the editor rename action ( F2 / LSP rename ).
Rename should update AST references across. rq files and matching `rq:idea`
comment idea tokens in source files.
refactor_support
Implemented by reqlan-rename-provider.ts, reqlan-comment-rename.ts, reqlan-name-provider.ts, and register-comment-rename-provider.ts.

refactor_symbol_move

reqlan rq/extension/refactor_support.rq

An idea declaration should offer a code action to move it to another. rq file.
Moving should cut the declaration from the source, insert it into the destination,
rewrite imports and references ( including comment references ), and reindex without
leaving duplicate idea rows for the old hosting file.
refactor_support refactor_changes
Implemented by reqlan-idea-refactor.ts, reqlan-code-action-provider.ts, and register-idea-refactor-commands.ts.

refactor_symbol_delete

reqlan rq/extension/refactor_support.rq

An idea declaration should offer a code action to delete it and update references.
Deleting should remove the declaration, clear or rewrite AST and comment references
that targeted it, and reindex affected files.
refactor_support refactor_changes
Implemented by reqlan-idea-refactor.ts, reqlan-code-action-provider.ts, and register-idea-refactor-commands.ts.

scope

reqlan rq/extension/scope.rq

these requirements describe the vscode extension and lsp for reqlan

lsp_support

reqlan rq/extension/scope.rq

the extension should provide an lsp server for . rq files , enabling navigation , validation , and computed views across the requirement graph

vscode_extension

reqlan rq/extension/scope.rq

the extension should integrate with vscode as the primary developer-user environment

extension_startup_reliability

reqlan rq/extension/startup-performance.rq

Reqlan startup must make the activity-bar shell and contributed commands available before optional indexing, parser construction, database initialization, or language-client startup can monopolize the extension host.
The implementation contract is first_paint_contract, deferred_startup_sequence, lazy_runtime_dependencies, and development_bundle_freshness.
Operational diagnosis follows startup_diagnostics.
activation_sequence loading_state nonblocking_index extension_bundle

Status: done

observed_failure

reqlan rq/extension/startup-performance.rq

Failure signature:
- Reqlan contributes its activity-bar container and header buttons from `package.json`, but the Context view remains on VS Code's built-in spinner before the extension-owned " Loading Reqlan … " shell.
- Contributed commands may be visible as menu items yet fail with `command 'reqlan.*' not found`.
- The extension-host CPU profile can be mostly idle after the failure.
This combination means static manifest contributions loaded but the extension module failed before `activate()` registered command handlers and the webview provider.

invalid_url_activation_failure

reqlan rq/extension/startup-performance.rq

The concrete incident failed while requiring `out/extension/main.cjs`, before `activate()` ran:
`TypeError: Invalid URL` in `embedPhysicsCoreSource`.
Runtime `readFileSync(new URL(..., import.meta.url))` is unsafe when esbuild emits CommonJS for an ES2017 target: `import.meta.url` is unavailable / empty and source-relative assets do not exist beside the bundled entry.
The fix generates and imports `PHYSICS_CORE_CLASSIC_SOURCE` at build time instead of resolving the source file at extension runtime.
html-export-assets.ts
generate-physics-core-source.mjs

Status: done

extension_host_process_model

reqlan rq/extension/startup-performance.rq

One Node extension-host process for the development window is normal; multiple workers are not required for a healthy Reqlan activation.
The language server is a separate child process launched only after extension activation reaches `LanguageClient.start()`.
Therefore an idle extension host with no Reqlan language-server child is consistent with an earlier module-load / activation failure, not evidence that a worker is missing.

first_paint_contract

reqlan rq/extension/startup-performance.rq

The platform spinner ends only after VS Code loads the host module, calls `activate`, the provider registers, and `resolveWebviewView` assigns HTML.
Reqlan assigns the lightweight HTML / Svelte shell first.
The webview installs its host message listener, mounts, waits for its first animation frame, then posts the one-shot `ready` signal from a queued task.
Index discovery / sync waits for that post-paint signal so synchronous parser or database setup cannot race the first visible frame.
first_paint_startup
App.svelte
app.svelte.ts
startup-gate.ts

Status: done

deferred_startup_sequence

reqlan rq/extension/startup-performance.rq

Required order:
1. Load the smallest practical host entry.
2. Synchronously register commands and the activity-bar provider; return from `activate`.
3. Assign the activity-bar shell and wait for the post-first-frame `ready` handshake.
4. Start index discovery / sync after `ready`; if the sidebar stays closed, start after a bounded three-second fallback so startup indexing and watchers are not lost.
5. Start the language client after `ready`, with a one-second fallback so language features work when the sidebar stays closed.
6. Report incremental index progress inside the already-painted sidebar.
The ready signal and both startup paths are one-shot / idempotent.
background_startup

Status: done

lazy_runtime_dependencies

reqlan rq/extension/startup-performance.rq

Base discovery must be cheap:
- Constructing `WorkspaceIndex` does not construct Langium / Chevrotain services; services are memoized on first parse.
- sql. js asm is not parsed as part of `main.cjs`; both index stores dynamically import the generated vendor bundle when a database first opens.
- Export / physics source is generated at build time rather than read via extension-runtime URLs.
The host bundle consequently fell from approximately 11. 2 MB to 2. 66 MB; sql. js occupies a separate approximately 8. 0 MB lazy vendor bundle.
workspace-index.ts
sqlite-store.ts
index-diagnostics-store.ts
esbuild.mjs

Status: done

development_bundle_freshness

reqlan rq/extension/startup-performance.rq

F5 executes `package.json.main` ( `out/extension/main.cjs` ), not TypeScript source.
`out/`, generated webview media, and copied syntaxes are gitignored, so launching without a build can run missing or stale artifacts even when source already contains the fix.
`.vscode/launch.json` therefore uses a deterministic pre-launch task that invokes the extension build orchestrator directly; root `pnpm run build:ext` delegates to the same script.
The task content-fingerprints Langium and physics generation, each webview, packaging media, and extension-host / language-server output; `tsc -b` retains project-reference incrementality. Unchanged artifacts are verified and skipped before the development host opens.
Watch mode remains useful during iteration, but concurrent watchers do not restart an already-running extension host or language-server child; stop and start F5 after host / server changes.
launch.json
tasks.json

Status: done

startup_diagnostics

reqlan rq/extension/startup-performance.rq

Diagnosis order:
1. Read the development extension host's `remoteexthost.log`; find `ExtensionService#_doActivateExtension reqlan.reqlan-extension`.
2. Distinguish code-loading time, activate-call time, and activate-resolved time.
3. If activation failed, use the first Reqlan stack frame rather than inferring a CPU hang.
4. If manifest UI exists but every command is missing, investigate module load / activation before indexing or webview data.
5. If the extension-owned " Loading Reqlan … " shell appears, provider resolution succeeded; subsequent delays belong to webview bootstrap or index readiness.
6. Confirm `out/extension/main.cjs` is newer than changed source and includes lazy `import("./vendor/sql-asm.cjs")`.
CPU-idle profiles do not disprove activation failure: once `require()` throws, the host can remain healthy and mostly idle while Reqlan stays unregistered.

activation_events_learning

reqlan rq/extension/startup-performance.rq

Modern VS Code derives activation for contributed views and commands.
The incident log explicitly showed activation event `onView:reqlan.activityBar`, so the missing-command failure was not caused by a missing explicit `onView` entry.
Activation-event changes should be justified from host logs and target-version behavior, not used to mask a module-load exception.

verification_contract

reqlan rq/extension/startup-performance.rq

Startup changes are complete only when:
- The production extension build succeeds and emits both `out/extension/main.cjs` and `out/extension/vendor/sql-asm.cjs`.
- The main bundle does not contain the sql. js asm implementation and imports the vendor lazily.
- The lazy vendor can initialize a database.
- Extension startup-gate and analytical lazy-service tests pass.
- Activity-bar shell paint is visually checked in a newly restarted F5 development host; activation failures are cached for the lifetime of a failed host session.
- Requirement analysis resolves the updated startup graph.

Status: done

complementary_information_rendering

reqlan rq/extension/syntax/features-syntax-highlighting.rq

The extension should render computed information inline in the editor as complementary text.
Complementary rendering should include resolved references and optionally indirect references behind a toggle.
Complementary rendering should not mutate source files unless the user explicitly applies a change.

reference_rendering

reqlan rq/extension/syntax/features-syntax-highlighting.rq

Resolved references should be visually distinguishable from unresolved or broken references.
Indirect references inferred by graph traversal should be showable via a user toggle.
Reference kinds ( dependency, incompatible with, applies to, related to ) should be surfaced where declared or inferred.

reference_resolution_folder

reqlan rq/extension/syntax/features-syntax-highlighting.rq

If the reference path is a folder, the extension should render a popup with a list of files in that folder.
The link should not try to resolve to a file if it doesn't exist.

activity_bar_module

reqlan rq/extension/syntax/features-syntax-highlighting.rq

the extension should provide a activity bar module for the ide.
the activity bar module should display the following information:
- the current file
- the current idea
- ideas referencing the current idea / selection
- a local graph
see activitybar.rq for more details.

reference_code_completion

reqlan rq/extension/syntax/features-syntax-highlighting.rq

references should code complete the available namespace of ideas
this includes both ideas using hte standards idea namespace syntax, and ideas using file paths, and relative file paths.
Implemented by reqlan-completion-provider.ts.
code_completion.rq

Tags: autocompletion

reference_code_completion_sequencing

reqlan rq/extension/syntax/features-syntax-highlighting.rq

reference_code_completion should be offered, not alphabetically, but by distance, then alphabetically.
Implemented by reqlan-completion-provider.ts.
code_completion

attribute_code_completion_main_descriptiption

reqlan rq/extension/syntax/features-syntax-highlighting.rq

the main description attribute is expected to be prose, so, the dropdown shouldn't be rendered in this context.

attribute_code_completion_attribute_key

reqlan rq/extension/syntax/features-syntax-highlighting.rq

the attribute key should complete based on endorsed keys and what is present in the index
i. e. after the @ symbol at the start of a line, the used attributes should be completed.
subsquently, values of the attribute key should be completed based on the values in that attribute key.

view_references_as_inlay_hints

reqlan rq/extension/syntax/features-syntax-highlighting.rq

References should be shown as inlay hints in the editor.
This should be a toggleable setting, which should be available in the command palette.
N-lines ( configurable setting ) of hints should be shown below the idea.
Implemented by reqlan-inlay-hint-provider.ts, reqlan-inbound-reference-inlay-label.ts, reqlan-inlay-hint-settings.ts, and register-reference-inlay-hints.ts.

Status: incomplete

traceable_inlay_hints

reqlan rq/extension/syntax/features-syntax-highlighting.rq

Inlay hints should be traceable, i. e. if a user clicks a specific idea reference, it should open that idea, if a user clicks the all references hint, it should open a search webview with the idea preselected / targets prefiltered
Implemented by reqlan-inbound-reference-inlay-label.ts, reqlan-inlay-hint-provider.ts, and register-webview.ts.

Status: done

inbound_inlay_hints_whole_graph

reqlan rq/extension/syntax/features-syntax-highlighting.rq

Inbound references shown in view_references_as_inlay_hints should include referencers from the whole requirement graph across the workspace, not only ideas declared in the current file.
Implemented by reqlan-inbound-reference-inlay-label.ts, reqlan-inlay-hint-provider.ts.
view_references_as_inlay_hints
traceable_inlay_hints

Status: done

code_lens_reference_types

reqlan rq/extension/syntax/features-syntax-highlighting.rq

References should have a codelens button.
The button should be togleable in settings.
The button should the classification of the reference. e. g. ' open reqlan file', " open { extension } file', ' open folder', ' open idea'
Clicking the CodeLens should open a reference card with summary stats — not navigate, because references already act as editor links.
The card should offer open / reveal / file-selector actions when useful.
Folders should be handled by focusing on the ide explorer, or by opening a file selector.
Some summary stats should be shown for references - e. g. last edited, count of references, count of referencers, etc.
Implemented by reqlan-code-lens-provider.ts, reqlan-reference-code-lens.ts, reqlan-code-lens-settings.ts, register-reference-code-lens.ts, and reference-code-lens-card.ts.

Status: done

syntax_features

reqlan rq/extension/syntax/features-syntax.rq

The extension should provide language support for. rq files via the lsp.
Syntax features should cover ideas, ideasets, imports, references, attributes, comments, and lists.
Broken imports and references should be validated and reported in the editor.
Go-to-definition and find-references should work for ideas, imports, and cross-file links.
Autoformatting should be supported for. rq files.

syntax_highlighting

reqlan rq/extension/syntax/features-syntax.rq

. rq files should receive full syntax highlighting coverage for all reqlan constructs.
Semantic token highlighting should distinguish ideas, attributes, references, imports, and keywords.

syntax_hovering

reqlan rq/extension/syntax/features-syntax.rq

Hovering on an idea, ideaset, import, or reference should show a text summary of its content and resolved target.
Hovering on a reference should show where it resolves and any declared reference kind.

comment_support

reqlan rq/extension/syntax/features-syntax.rq

The extension should recognise reqlan references embedded in comments of arbitrary source files.
Comment reference syntax should follow the form `rq:"../reqfile.rq".idea_name` in line comments.
Comment references in non-. rq files should support syntax highlighting, hover, and go-to-definition.
Arbitrary file references should be supported from both. rq files and comment references.

code_completion

reqlan rq/extension/syntax/features-syntax.rq

The extension should support sensible code completion.
- support for references
- support for imports, including import-root alias paths such as `@/` from configuration_import_root_alias and configuration_import_roots
- support for semantic search
- support for graph-proximity based ranking

refactor_support

reqlan rq/extension/syntax/features-syntax.rq

syntactic symbols should be available for renaming, moving, and deleting. the extension should watch for the change.
Detailed behaviour lives in refactor_support.rq.
Implemented by reqlan-rename-provider.ts, reqlan-idea-refactor.ts, and index.ts.

file_references

reqlan rq/extension/syntax/features-syntax.rq

A file reference should act as a link in the editor.
If the target file is empty or has a parse error, the link should remain available and clickable, but should show a warning underline.
Implemented by reqlan-file-link-resolver.ts, reqlan-document-link-provider.ts, reqlan-definition-provider.ts, and reqlan-validator.ts.

sensible_alias_support

reqlan rq/extension/syntax/features-syntax.rq

if an imported idea shares a name with an idea in the current file:
When the import uses an alias, the base name may be reused locally — see import_tokenisation.

at_sign_in_idea_text_block

reqlan rq/extension/syntax/features-syntax.rq

the @ symbol should only indicate an attribute if at the start of a line.
it should be escapeable with a backslash ( although any character would work as the @ would no longer be at the start of the line )
so @ this_is_not_an_attribute

code_completion_import_file_paths

reqlan rq/extension/syntax/features-syntax.rq

import files should code complete nicely based on the current file's path; and the resolved import config.
it should support normal ".. / string / paths "; and if " @ / the-paths / are- @ - aliased "
configuration.rq
imports.rq
code_completion.rq

codelens

reqlan rq/extension/vsc-primitives.rq

—

code_completion

reqlan rq/extension/vsc-primitives.rq

—

inlay_hints

reqlan rq/extension/vsc-primitives.rq

—

code_actions

reqlan rq/extension/vsc-primitives.rq

—

quick_fixes

reqlan rq/extension/vsc-primitives.rq

—

index

reqlan rq/indexer/indexer.rq

The ideas graph indexer: parse `.rq` with `@reqlan/language`, extract ideas / edges, persist to sql. js SQLite.
Owned by ownership; consumed per consumption.

ownership

reqlan rq/indexer/indexer.rq

The index / indexer lives in `packages/analytical` ( `@reqlan/analytical` ).
Canonical single-base engine: workspace-index.ts ( `WorkspaceIndex` facade ).
Sync / idle impl: workspace-index-sync.ts; one-file parse + persist: workspace-index-file.ts; mtime stale diff: workspace-mtime.ts.
Multi-base registry: one `WorkspaceIndex` per discovered base under application_memory ( `<base>/.reqlan/` ).
Headless entry: create-runtime.ts via `createAnalysisRuntime` ( CLI / MCP ) — discovers bases under the resolved root and defaults to the nearest base containing cwd.
On-disk store path: application-memory.ts under `<base>/.reqlan/` — see application_memory.

consumption

reqlan rq/indexer/indexer.rq

Consumers of the analytical index:
- extension — thin VS Code adapter index-service.ts ( file watchers, Uri conversion, UI status )
- CLI ( `cli_package` ) and MCP — headless create-runtime.ts
The extension does not own the indexing engine; it only hosts the adapter.

nonblocking_index

reqlan rq/indexer/indexer.rq

Index sync must stay non-blocking for the host UI ( notably activity_bar and workspace_loading ).
Editor startup is gated by first_paint_startup; discovering a base must not construct Langium services, which are initialized lazily on the first parse.
While syncing, surface progress — state, processed / total, and the current file — in workspace_pane and index_panel.
In-flight sync must be cancellable from those surfaces; cancel keeps already-indexed rows and returns the index to ready.
Incremental behaviour ( see also indexing_incrementality ):
- Single-file create / change / delete via watchers indexes only that file — never a full base walk.
- Soft full sync ( `syncWorkspace` / Refresh ) skips parse + persist when the file's mtime matches the value stored on the documents row.
- Hard refresh ( `clearAndRebuildIndex` / Clear & rebuild ) wipes the store and reindexes every file.
Implemented by workspace-index.ts; editor adapter index-service.ts.

Status: done

triggers

reqlan rq/indexer/indexer.rq

Index refresh behaviour ( capability detail in features-graph-analysers.rq ):
- indexing_incrementality / nonblocking_index — incremental where possible
- indexing_trigger_filesave / idea_index_triggers — on `.rq` file change
- indexing_trigger_manual — manual reindex commands
- indexing_trigger_open — one soft sync after the activity-bar first-paint gate
- indexing_trigger_auto — idle background mtime staleness check ( cheap; not a full reindex )
Editor watches + idle scheduler: index-service.ts; headless syncs on runtime activate.

capabilities

reqlan rq/indexer/indexer.rq

Product capabilities over the index: index_ideas, index_technology, and sibling analysers in that file.
Indexing performance timing and diagnostic UI: index_diagnostics.

index_diagnostics_timing

reqlan rq/indexer/indexer.rq

Soft sync and per-file index paths record durations into the diagnostic index under index_diagnostics_store.
See index_diagnostics_metrics.
Must not block nonblocking_index; recording failures are swallowed / logged by the store and must not fail the sync.

index_code_files

reqlan rq/indexer/indexer.rq

The indexer should be able to index non-rq files as well for comment references.

attribute_configuration

reqlan rq/language/attributes.rq

The extension should be largely unopinionated about attributes, allowing users to extend as they see fit.
attributes should be as slim as possible to allow for minimised bloat.

import_keywords

reqlan rq/language/imports.rq

The keywords import, from, and as are reserved for import statements.
Import keywords may also appear as ordinary words in idea body text when not at statement start.

import_from

reqlan rq/language/imports.rq

From-import syntax uses from, a quoted path, import, and an idea name.
From-import may include an alias using as.

import_error_recovery

reqlan rq/language/imports.rq

A malformed import must not invalidate the rest of the file.
Recoverable invalid `from` shapes parse as local import nodes with a line-level diagnostic:
- `from "path" as alias` ( mistaken namespace form ) — suggest `import "path" as alias` or `from "path" import <idea>`
- bare `from "path"` — require the `import <idea>` clause
- `from` without a quoted path — consume the remainder of the line as an invalid import
Later imports and top-level ideas continue to parse and link normally.
Same recovery posture for nameless top-level braces: no_name_idea_safe_warning.
If lex / parse never completes, see parse_budget_timeout.

import_namespace

reqlan rq/language/imports.rq

Namespace import syntax uses import and a quoted path.
Namespace import may include an alias using as.
A bracket reference to the alias alone — for example context_model — opens the imported file and links only the alias name, like an ideaset namespace.
Qualified references through the alias — for example builder — resolve ideas from the imported module.

import_qualified

reqlan rq/language/imports.rq

Qualified import syntax uses import, a quoted path, a dot, an ideaset name, a dot, and an idea name.
Qualified import may include an alias using as.

import_paths

reqlan rq/language/imports.rq

Import path strings may use relative paths such as. / exampleimport. rq.
Import path strings may use paths containing folders.
Import path strings may use remote urls such as https: / / company. com / reqs / style. rq.
Import path strings may use an import-root alias shorthand such as `@/path/relative/to/import/root`; see configuration_import_root_alias.
Path forms apply to from-import, namespace import, and qualified import; see import_from, import_namespace, and import_qualified.
Editor completion for path strings is covered by code_completion.

configuration_import_root_alias

reqlan rq/language/imports.rq

An import path may start with an alias string, then `/`, then a relative path under that alias's import-root directory.
Default alias string: `@`, written as `@/` plus a path relative to the import root.
Default import-root directory: the workspace folder that contains the `.rq` file ( not the document directory ).
The path after `/` is joined to that alias's import-root directory; the alias itself must be followed by `/` ( e. g. `@reqs` is not aliased ).
Alias strings and import-root directories are configured as configuration_import_roots in the applying `.reqlan/config.json` from configuration_location.
A configured relative `root` resolves against the base root ( parent of `.reqlan` ); an omitted `root` keeps the workspace-folder default.
When several configured aliases could match a path, the longest alias wins.
Related path forms: import_paths. Completion: code_completion.

anonymous_imports_allowed

reqlan rq/language/imports.rq

imports can be inlined with this syntax: `attribute`. i. e. file references import the file as an ideaset.

import_tokenisation

reqlan rq/language/imports.rq

if an import is given an alias, then the base name is still available as a variable name and should not cause a conflict.
Only the alias binds in the importing file; the imported idea's base name may be reused for a local idea.
e. g.
The same rule applies to qualified imports with `as`.
Unaliased imports still bind the idea name and conflict with a local idea of that name.
Related: sensible_alias_support.

lexer_bridge_to_syntax

reqlan rq/language/parser_lexer.rq

The context-sensitive token builder is what makes block_idea and prose braces coexist:
structural `{` / `}` are only those that open or close ideas, while nested_curly_braces stay body text.
context_sensitive_lexer_scaling is the performance contract for that bridge; code_snippets is the opacity contract so fence interiors never feed the brace timeline.

recovery_vs_budget

reqlan rq/language/parser_lexer.rq

no_name_idea_safe_warning and import_error_recovery keep a * finished * parse usable after local mistakes.
They do not help when lex / parse never returns — that failure mode is parse_budget_timeout.
Workspace load still isolates per-document throws so one bad file cannot abort LSP init; the budget turns non-termination into the same “ leave this file unloaded ” outcome, with diagnostics.

parse_budget_timeout

reqlan rq/language/parser_lexer.rq

Lexing, parsing, or a parse subprocess for a single `.rq` file must finish within a wall-clock budget.
If it cannot, do not hang the language server or block the rest of the workspace.
Surface both a warning ( budget exceeded; semantic features may be incomplete ) and an error ( file left unloaded ) on that document, then continue with other files.
Happy path stays in-process ( sync ) for typical file sizes so edits and workspace load stay fast.
Killable worker enforcement is used when the input is large, a file previously hit the budget ( sticky escalate ), or a caller forces the worker path; sync throws still become the same incomplete result shape.

Status: done

syntax_whitespace

reqlan rq/language/syntax_whitespace.rq

whitespace is not significant in attributes.
this line is not an idea, it is part of the main content attribute attribute

nested_curly_braces

reqlan rq/language/syntax-edge-cases.rq

if there is a prose block containing curly braces, { such as this one } they should be treated as part of the prose.
Matching braces that end a line — including adjacent pairs like { { SITE_URL } } — stay in the body; they must not close the enclosing idea.
A lone `}` on its own line still closes the structural block so an unbalanced prose `{` cannot swallow the idea closer.

context_sensitive_lexer_scaling

reqlan rq/language/syntax-edge-cases.rq

Context-sensitive token classification for structural / prose braces and top-level import keywords must remain linear in document size.
The lexer records brace-depth changes sparsely ( not per-character tables ) and looks them up in log time while tokenising, so workspace language-server initialization and editor re-lexes stay bounded.
Code fences are skipped during the brace scan so example braces cannot inflate work or desync depth.
Bounded work still assumes the lexer / parser * returns *; unbounded hangs are cut by parse_budget_timeout.

Status: done

one_liner_curly_brace_context

reqlan rq/language/syntax-edge-cases.rq

this should { be acceptable } as well

closing_nested_curly_braces

reqlan rq/language/syntax-edge-cases.rq

if, for some reason, there is a prose block containing only closing curly braces, they should be escaped and allowed \ } like this.

file_suffix

reqlan rq/language/syntax.rq

Reqlan requirement documents use the . rq file suffix .

file_layout

reqlan rq/language/syntax.rq

A file begins with zero or more import statements, followed by top-level ideas and ideasets.
The file forms an implicit ideaset; its name may default to the filename without the suffix.
Front matter syntax is not yet specified.

Status: incomplete

idea_name

reqlan rq/language/syntax.rq

Idea names are identifiers or double-quoted strings.
Unquoted names follow identifier rules and may use letters, digits, underscores, and dashes, for example myidea, my_idea, or dash-or_underscore_delimited-idea.
Quoted names allow spaces and other characters when wrapped in double quotes.
Idea names must be unique within their ideaset or file.
Idea names should not use reserved keywords.

simple_idea

reqlan rq/language/syntax.rq

A one-liner idea is written as a name followed by unstructured body text on the same line.
A name-only idea is a one-liner with just the name and no body text.
One-liner ideas do not use curly braces and do not continue onto subsequent lines.

block_idea

reqlan rq/language/syntax.rq

A block idea is written as a name followed by curly braces containing a body and optional attributes.
The first unstructured text in an idea body is the main description when no other body attribute is marked.

main_desription_lists_allowed

reqlan rq/language/syntax.rq

- lists are valid in.
- so this should not raise any error. s

ideaset

reqlan rq/language/syntax.rq

An ideaset is a parenthesized, comma-separated list of idea names.
Ideaset members may be unquoted identifiers or quoted strings.
Ideasets act as namespace containers for ideas, nested ideasets, and references.

reference_brackets

reqlan rq/language/syntax.rq

Single-bracket references use square brackets around a target.
Forms include ideaset-only, idea-only, ideaset dot idea, and idea dot attribute targets.

same_file_reference

reqlan rq/language/syntax.rq

reference_brackets should work if the target is either imported, or it is in the same file.
Forward references to ideas declared later in the file are valid.
Circular references between ideas in the same file are valid.
So, this idea should not throw an error.

reference_wikilink

reqlan rq/language/syntax.rq

Double-bracket wikilinks use doubled square brackets around a target.
Wikilinks may include an obsidian-style alias pipe with a display label after the target.
A bare pipe character in body prose — for example kind: idea | file | selection — is plain text, not wikilink syntax.

reference_qualified

reqlan rq/language/syntax.rq

Cross-file references may qualify an import path or alias with an idea name.
Qualified wikilinks may combine a quoted import path with a dot and idea name.

reference_file

reqlan rq/language/syntax.rq

References may target arbitrary files, not only. rq files.
File reference syntax uses a bracketed quoted path.
Line or line-range references append L # and services after the path inside the brackets.
Symbol references append a dot-separated symbol path after the quoted file path.

string_and_reference_apostrophes

reqlan rq/language/syntax.rq

strings should use double or single apostrophes interchangeably and support backslash escapes.

reference_embedding

reqlan rq/language/syntax.rq

References may appear inline in description, plan, or other attribute values.
References may be declared explicitly in @ references or implied by mention elsewhere.
Reference kinds include dependency, incompatible with, applies to, and related to.
References may use wildcards and apply to namespaces or ideasets.

attribute_marker

reqlan rq/language/syntax.rq

Attributes are introduced with the @ prefix.
Attribute names follow identifier rules.

attribute_forms

reqlan rq/language/syntax.rq

A bare attribute name after @ denotes a true flag or render keyword.
A negated flag uses a trailing bang after the attribute name.
A valued attribute uses a space after the attribute name followed by a value.
A colon after the attribute name is optional legacy syntax and is not part of the value.
Common attributes include plan, status, priority, criticality, confirmation, owner, log, tags, and references with the @ prefix.
Any custom attribute name is allowed.

attribute_location

reqlan rq/language/syntax.rq

Marked attributes must be at the start of a line. @ this_is_not_an_attribute

attribute_values

reqlan rq/language/syntax.rq

Attribute values may be unstructured scalar text on the same line.
Attribute values may be block values in curly braces.
Attribute values may be list values in parentheses.

lists

reqlan rq/language/syntax.rq

Parenthesized lists contain newline-separated items.
Each list item is either a one-liner or a nameless block idea in curly braces.
Lists may appear as attribute values and inside block bodies.
Named lists use a label followed by a parenthesized item list; the opening parenthesis must be followed by a newline before the first item.
Nested lists may appear inside block values or as list items; the opening parenthesis must be followed by a newline before the first item.
Inline parentheses in body prose — for example continuous ( " live " ) physics or ( pixelRatio 1, no WebGL ) — are plain text, not lists.

comments

reqlan rq/language/syntax.rq

Line comments use double slash through end of line.
Block comments use slash-star and star-slash delimiters and may span multiple lines.
Meta comments on the same line after content are allowed.
Comments should not be triggered in a string context - e. g. a ' https: / / not a comment. com', " https: / / not a comment. com ", or `https://not a comment.com`
" / / also not a comment "
" " "
" " "
' that doesn't start a comment

comment_reference_ignore

reqlan rq/language/syntax.rq

Comment reference ignore syntax uses `//rq-ignore-error`.
Comment reference ignore suppresses diagnostics on the immediately following line.

code_snippets

reqlan rq/language/syntax.rq

Idea bodies and block attribute values may embed fenced code blocks delimited by triple backticks.
An opening fence is three backticks on a line, optionally followed by a language tag such as python or rq.
A closing fence is three backticks on a line.
Everything between the fences is literal opaque text — it is not parsed as reqlan syntax.
Keywords, imports, attributes, braces, and quotes inside a fence are inert for the parser and may be shown as examples without parse errors.
Fenced blocks may span multiple lines and preserve their inner content verbatim.
Brace-depth tracking must skip fence interiors so example braces cannot desync surrounding structure ( no_name_idea_safe_warning ).

comment_reference

reqlan rq/language/syntax.rq

Reqlan references may appear in line comments of arbitrary source files.
Comment reference syntax uses rq, a colon, a quoted path, a dot, and an idea name.

string_literals

reqlan rq/language/syntax.rq

String literals in import paths and quoted idea names may use double or single quotes.
Escaped characters inside strings follow standard backslash escaping.

naked_strings_in_body

reqlan rq/language/syntax.rq

Quoted text in idea bodies, attribute values, and list items is plain prose, not a string literal.
Quote characters are preserved in the body text. For example, " Fit to view " in a bullet line is body text.
String literals are reserved for import paths, top-level quoted idea names, and quoted paths inside bracket references.

markdown_links

reqlan rq/language/syntax.rq

markdown style links should be supported. label where label can be anythign and not be treated as reference

round_brackets

reqlan rq/language/syntax.rq

Round brackets indicate a list of ideas or attributes. Items may be separated by commas or newlines.
Attribute list values may use commas or newlines; see @ example_list_attribute_using_commas and @ example_list_attribute_using_newlines.
Parentheses in body prose — including API call shapes like cytoscape. animate ( { fit, easing: ' ease-out-cubic ' } ) — are plain text, not list syntax.

subidea1

reqlan rq/language/syntax.rq

hello

subidea2

reqlan rq/language/syntax.rq

hi, i'm a subidea

example_ideaset

reqlan rq/language/syntax.rq

Ideaset (example_ideaset)

references_to_subidea

reqlan rq/language/syntax.rq

It should be acceptable to reference subidea1

no_name_idea_safe_warning

reqlan rq/language/syntax.rq

A top-level nameless curly-brace block — `{... }` with no idea name — must not take down the parser or the language server workspace.
Parse the block as a recoverable anonymous top-level element, emit a descriptive warning that a name is required before `{`, and continue so later ideas, imports, and links still work.
Nameless blocks inside parenthesized lists remain valid list items per lists; only top-level nameless blocks warn.
Related recovery posture: import_error_recovery. Block shape: block_idea. Fenced examples must stay opaque per code_snippets so braces inside snippets cannot desync structural depth.
Non-termination ( lex / parse never finishes ) is a different failure mode: parse_budget_timeout.

Status: done

dash-or_undersore_delimited-idea

reqlan rq/language/syntax.rq

it should be possible to use dash or underscore delimited idea names .

name_only_ideas_it_should_be_possible_to_use_name_only_ideas_without_a_body

reqlan rq/language/syntax.rq

—

semantic_engineering_toolset

reqlan rq/marketing_and_media/marketing.rq

—

smart_engineers_use_reqlan

reqlan rq/marketing_and_media/marketing.rq

—

tutorials

reqlan rq/marketing_and_media/tutorials.rq

Tutorial media teaches reqlan through short, scripted videos plus copy-pasteable `.rq` examples.
Content must reflect mission_statement: semantic requirements as code for people working with LLMs, with ergonomic definition and consumption.
Three series — do, then name, then craft:
- get_started_series: first-hour fluency ( write, link, create a base, neighbourhood, AI slice, code ).
- concepts_series: ontology vocabulary, an extension surface map, and the cli_package headless surface after the learner has felt the loop.
- advanced_series: graph craft, AI workflows, distribution.
Host on the marketing site per tutorials_section and link from extension onboarding per installation_event and phonebook.
Visual language follows brand; on-screen chrome stays quiet per show_dont_tell — narration carries concepts, UI does not lecture.

Status: draft

Tags: marketing, media, tutorials

tutorial_philosophy

reqlan rq/marketing_and_media/tutorials.rq

Producers may cite mission_statement, llm_first, vsc_first, general_purpose, simplicity, and inspiration as constraints on what an episode must prove. These shape production choices — they are never spoken to, or shown to, the learner.
Production guidance per constraint:
- llm_first: demonstrate focused context — search, local slice, add-to-context — by doing it on camera before pasting a whole workspace. Never let VO or a slide label the workflow as a philosophy.
- vsc_first: primary demos live in VS Code / compatible editors with the extension installed.
- general_purpose: at least one get-started beat and one advanced beat use a non- " enterprise software " framing ( personal knowledge, ops checklist, or creative brief ).
- simplicity: start with one-liners and one file; introduce braces, imports, and attributes only when the viewer feels the need.
Show, then name: write a real idea, link it, create a base, open the activity bar — then put names to what the learner already did in concepts_series.
Hard rule — learner-facing surfaces must never lecture. VO, any on-screen text the viewer reads ( title cards, end cards, callouts, quiz prompts ), slide heading / body / fragments / notes, try-this prompts, and fixture prose inside `@example` must NOT name:
- product philosophy or constitution principles ( " llm-first ", " mission ", " semantic requirements as code ", " token discipline " );
- design lineage ( Obsidian, industrial control, " ontology " as a brand concept );
- syllabus pedagogy ( " verbs then nouns ", " teaches judgement " );
- taste lectures ( " simplicity over scaffolding ", " calm tiles, not a laundry list ", " keep copy short " ).
Instead: show the workflow and the result, and name only surfaces and actions the user can perform.
Producer teaching-order note ( guidance for planning, not copy for the screen ): get-started demonstrates the core actions; concepts puts names to the building blocks; advanced shows judgement.

tutorial_format

reqlan rq/marketing_and_media/tutorials.rq

Production bar — every episode idea below must carry all of:
- Audience, Outcome, Runtime ( always present — including advanced packs )
- Demo — explicit pre-state of `reqlan-tutorials-demo` at cold open ( files present, caret, UI already open )
- Related — feature requirement links the episode proves; `@todo` if a demoed surface is not `@status done`
- `@example` — full recreateable fixture ( multi-file when the beat needs it ), fenced as opaque snippets when the sample itself contains braces
- `@script` — caption-ready spoken VO plus screen directions ( VO = voiceover; SCR = what to show ).
Structure: cold open → teach beats → misconception or recovery beat → try-this → end card.
Use exact Command Palette / chat paths. VS Code is primary; note Cursor skill / chat alternate when AI tools differ.
Use SCR: / VO: labels, not bracket tags, so they are not parsed as reference links.
Prefer denser beats over stretching runtime.
- `@slides` — one slide per major SCR beat ( ~ 7 – 10 ). Title, teach, try-this / end. `notes` = VO lines from `@script`.
Authored Reveal JSONC under decks is derived from `@slides` and may add JSONC-only fields
( `code_label`, dual-pane `code` / `code_b` ) for contrast beats.
Episodes are self-contained; series order is recommended: get-started → concepts → advanced.
After get-started 01 – 02, later get-started episodes can be sampled; concepts packs assume the loop was felt at least once.
Prefer 1080 p screen capture with a small inset face cam optional; logo end-card with site / marketplace links from phonebook.
Stay inside stated runtimes where possible ( get-started ~ 4 – 7 min, concepts ~ 8 – 12 min, advanced ~ 8 – 12 min ).

demo_workspace

reqlan rq/marketing_and_media/tutorials.rq

Shared recording workspace name: `reqlan-tutorials-demo`.
Never record against the reqlan monorepo itself — keep demos small and readable.
Cumulative fixture map ( end state after each milestone ):
- After gs_01: empty folder open ( or README only ); extension installed; onboarding seen once.
- After gs_02: `reqs/product.rq` with `product_name` one-liner and `welcome_flow` block. No `.reqlan` yet.
- After gs_03: `welcome_flow` ↔ `onboarding_checklist` linked; optional `account_model`. Still no `.reqlan`.
- After gs_04: `.reqlan/` with `config.json` and `.rqignore`; ideas index present as tooling memory. Folder is a base.
- After gs_05: same graph; viewer knows activity-bar sync, hop depth, copy-as-markdown.
- After gs_06: `password_rules` idea present; chat / skills exercised once.
- After gs_07: `reqs/auth.rq` with `login_api`; `src/login.ts` stub; file reference from idea to code.
Concepts assume the full get-started end state ( including `.reqlan` ).
con_03_cli uses the same fixture from a terminal at workspace root.
Advanced baseline tree:
Get-started 01 – 03 may start without `.reqlan`; from gs_04_first_base onward the folder is a real base.
Advanced episodes may add imports, attributes, comment refs, and the newsletter vignette on camera.

slide_pack_format

reqlan rq/marketing_and_media/tutorials.rq

Each published episode that ships a deck declares an `@slides` list.
Each slide item is an anonymous block with:
- id — stable slide handle
- transition — reveal transition name per slide_transitions
- background — theme key per slide_visual_system
- kicker / heading / body — on-screen copy ( minimal )
- code / code_lang — optional fenced snippet shown on the slide
- asset — key into presentation_assets
- fragments — optional comma-separated fragment labels ( fade-in )
- notes — speaker notes, usually the VO lines from `@script`
Authored deck JSONC under decks is the editable source of truth derived from `@slides`.
Authored catalog JSONC: manifest.jsonc.
Runtime deck JSON consumed by presentation_player_route is generated from those JSONC sources.
Standalone Reveal shell ( optional local serve ): player
Site embed and lesson routing follow tutorials_section and presentation_player_route.

slide_visual_system

reqlan rq/marketing_and_media/tutorials.rq

Brand from brand: dark rust base, aqua accent, pink highlight.
Quiet chrome per show_dont_tell — no dense labels on slides; narration carries detail.
Background keys: brand-dark, brand-panel, brand-contrast.
Typography: one heading, one short body, optional code block; logo on title and end cards.

slide_transitions

reqlan rq/marketing_and_media/tutorials.rq

Default deck transition: fade.
Use slide for section / series breaks.
Use none for side-by-side code-compare beats so the eye stays on the content.
Fragment animation: fade-in for try-this prompts and CTAs.

presentation_assets

reqlan rq/marketing_and_media/tutorials.rq

Shared files live under assets.
Required: logo ( copy of logo.svg ).
Optional placeholders: montage-ide, activity-bar, chat-search, file-link ( SVG or PNG keys referenced from decks ).
Public asset serving must stay aligned with assets.

slide_decks

reqlan rq/marketing_and_media/tutorials.rq

Ideaset (slide_decks)

get_started_series

reqlan rq/marketing_and_media/tutorials.rq

Ideaset (get_started_series)

get_started_series_brief

reqlan rq/marketing_and_media/tutorials.rq

Short " get started " series: seven episodes in get_started_series, about 4 – 7 minutes each, total under about 40 minutes.
Goal: a new user can install reqlan, write ideas, link them, create a base, inspect neighbourhood context,
ask the chat participant, and point ideas at real files.
Teaching order ( producer note, not on-screen copy ): demonstrate the core actions first; naming the building blocks waits for concepts_series.
Tone: calm and concrete on screen — no feature-tour survey ( that is con_02_extension_tour ).
End each episode with one " try this " prompt on screen.

Status: draft

Tags: get-started

gs_01_why_reqlan

reqlan rq/marketing_and_media/tutorials.rq

Audience: developers or knowledge workers who already talk to LLMs about their project and feel context drift.
Outcome: viewer can explain reqlan in one sentence and knows where install / docs live.
Runtime: 4 – 5 min.
Demo: cold open on a fresh machine or reset profile. Folder `reqlan-tutorials-demo` does not exist yet — or an empty folder with only `README.md`. No `.rq` files. reqlan extension not installed ( or disabled ) until the install beat.
Related: mission_statement llm_first inspiration installation_event installation extension_installation

gs_02_first_idea

reqlan rq/marketing_and_media/tutorials.rq

Audience: freshly installed users who finished gs_01 or equivalent.
Outcome: create a `.rq` file; write a one-liner and a block idea; save; see syntax highlighting and language mode.
Runtime: 5 min.
Demo: folder `reqlan-tutorials-demo` open in VS Code. Extension installed; onboarding seen once. Explorer shows empty tree or `README.md` only — no `reqs/` folder yet, no `.reqlan`.
Related: idea simple_idea block_idea simplicity file

gs_03_link_ideas

reqlan rq/marketing_and_media/tutorials.rq

Audience: users with at least one idea file from gs_02.
Outcome: use bracket references and a wikilink; peek definition and go-to-definition; understand ideas as a navigable graph.
Runtime: 6 min.
Demo: `reqlan-tutorials-demo/reqs/product.rq` open. Caret inside `welcome_flow`. File contains `product_name` one-liner and `welcome_flow` block only — no links yet, no `account_model`, no `.reqlan`.
Related: reference reference_brackets reference_wikilink idea

gs_04_first_base

reqlan rq/marketing_and_media/tutorials.rq

Audience: users with a small linked graph who have not yet marked a base.
Outcome: create a base ( `.reqlan` ); explain that a base is the boundary of one ideas graph and owns the ideas index; know extension install ≠ base create.
Runtime: 5 – 6 min.
Demo: `reqlan-tutorials-demo` with `reqs/product.rq` containing linked `welcome_flow` ↔ `onboarding_checklist` ( and optional `account_model` ). No `.reqlan` folder. Activity bar or Ideas Summary shows empty / create-base prompt. Caret on any idea in `product.rq`.
Related: base base_detail create_base_onboarding base_installation installation extension_installation

gs_05_activity_bar

reqlan rq/marketing_and_media/tutorials.rq

Audience: users with a small linked graph inside a base.
Outcome: open the reqlan activity bar; follow editor focus with sync; adjust hop depth; copy a slice as markdown; glance at Ideas Summary without treating it as a full dump.
Runtime: 6 – 7 min.
Demo: `reqlan-tutorials-demo` is a base — `.reqlan/` present and index active. `reqs/product.rq` with linked `welcome_flow`, `onboarding_checklist`, optional `account_model`. Caret inside `welcome_flow`. Activity bar closed or on a non-reqlan view.
Related: activity_bar local_graph_view ideas_summary llm_first implied_context base

gs_06_chat_search

reqlan rq/marketing_and_media/tutorials.rq

Audience: users ready to involve AI without abandoning the graph.
Outcome: invoke `@reqlan /rq-search` ( VS Code Chat ) or Cursor skill `rq-search`; find an idea by meaning; add to context; optionally build a requirement from intent.
Runtime: 6 min.
Demo: same base and `reqs/product.rq` as gs_05. Add `password_rules` if missing — otherwise type it live at cold open. No chat thread open yet. `.reqlan` index active.
Related: ai_integration chat_skill_naming ai_add_to_context ai_build_requirement mcp_tools command_palette

gs_07_link_code

reqlan rq/marketing_and_media/tutorials.rq

Audience: users with application source beside `reqs/` who completed gs_01 – 06.
Outcome: add a file reference from an idea to implementation; open the file from the requirement; see reverse scope when standing in code; recap the get-started loop into Concepts.
Runtime: 6 – 7 min.
Demo: base active. `reqs/product.rq` with linked ideas and `password_rules`. No `reqs/auth.rq` yet. No `src/` folder. Caret in `product.rq`. Explorer shows only `reqs/` and `.reqlan/`.
Related: any_file_scope context_scope reference referenced_files file

concepts_series

reqlan rq/marketing_and_media/tutorials.rq

Ideaset (concepts_series)

concepts_series_brief

reqlan rq/marketing_and_media/tutorials.rq

Short concepts series after get-started: three packs that put names to what the learner already felt.
con_01_ontology — the building blocks: idea, ideaset, file, base, reference, attribute, and the focused map view ( cartographic_map ).
con_02_extension_tour — where those building blocks appear across the extension surfaces.
con_03_cli — the headless twin: cli_package / commands on the same `.reqlan` index ( init, search, analyse, parse, export ).
Runtime: about 8 – 12 minutes each. Optional for impatient builders; recommended before advanced.

Status: draft

Tags: concepts

con_01_ontology

reqlan rq/marketing_and_media/tutorials.rq

Audience: viewers who finished get-started ( or equivalent ) and want shared vocabulary without repeating the install loop.
Outcome: define each core ontology noun in one sentence; place base as graph boundary ( including nesting ); distinguish attribute_body from optional `@` metadata; name cartographic_map as a chosen cut, not a mandatory dump.
Runtime: 10 – 12 min.
Demo: `reqlan-tutorials-demo` at get-started end state — `.reqlan/` present; `reqs/product.rq`, `reqs/auth.rq`, `src/login.ts`; caret starts on `welcome_flow` in `product.rq`.
Related: idea ideaset file base base_detail reference attribute attribute_body cartographic_map referenced_files configuration base_nesting multi_base_environment

con_02_extension_tour

reqlan rq/marketing_and_media/tutorials.rq

Audience: viewers who know the ontology nouns and want a calm map of where they appear in the product.
Outcome: name the primary extension surfaces and which job each owns; know where not to dig on day two.
Runtime: 8 – 10 min.
Demo: full get-started end state of `reqlan-tutorials-demo` ( `.reqlan`, `reqs/product.rq`, `reqs/auth.rq`, `src/login.ts` ); activity bar closed; Ideas Summary closed; chat available.
Related: extension activity_bar ideas_summary command_palette ai_integration html_export graph_view local_graph_view simple_views chat_skill_naming installation mcp_tools cli_package commands

con_03_cli

reqlan rq/marketing_and_media/tutorials.rq

Audience: viewers who finished the extension tour and want the headless twin named — CI, scripts, and agents without living in the editor.
Outcome: install and run `reqlan` / `rq`; init a base; run search, analyse, and parse; know `--cwd` / `--json` and one-base-per-run; know export shares html_export with the extension.
Runtime: 9 – 11 min.
Demo: advanced get-started end state of `reqlan-tutorials-demo` — `.reqlan` indexed, `reqs/product.rq` + `reqs/auth.rq` present; integrated terminal at workspace root; extension idle in background ( not the focus ).
Related: cli_package commands init html_export base multi_base_environment llm_first function_parity

advanced_series

reqlan rq/marketing_and_media/tutorials.rq

Ideaset (advanced_series)

advanced_series_brief

reqlan rq/marketing_and_media/tutorials.rq

Advanced series: eight episodes in advanced_series, about 8 – 12 minutes each, plus adv_overview.
Assumes get-started fluency and ideally concepts_series vocabulary ( or equivalent ).
Goal: multi-file graphs, purposeful attributes, cartographic navigation, AI token discipline,
code-comment traceability, HTML publishing, headless CLI / MCP craft ( beyond con_03_cli ), and modelling patterns that stay readable.
Include at least one non-software vignette ( ops runbook or editorial brief ) to honour general_purpose.
Bases appear as craft judgement ( active base, nested boundaries ) — not a second create-base lesson.
Decks: advanced_series_brief and adv_01 – adv_08 under slide_decks.

Status: draft

Tags: advanced

adv_overview

reqlan rq/marketing_and_media/tutorials.rq

Audience: viewers who finished get-started and concepts ( or equivalent ) and want the map of craft themes before committing to a deep dive.
Outcome: name the eight advanced themes, understand how they connect to get-started discipline, and pick a first episode.
Runtime: 3 – 4 min.
Demo: `reqlan-tutorials-demo` at advanced baseline — multi-file graph, `.reqlan` present, no new files typed; montage only.
Related: advanced_series_brief general_purpose llm_first concepts_series base multi_base_environment

adv_01_imports_ideasets

reqlan rq/marketing_and_media/tutorials.rq

Audience: builders with a single-file graph who feel reference sprawl or duplicate idea names across files.
Outcome: split ideas across files; use `from` / `import` and namespace import; group with ideasets; resolve qualified references without breaking call-site readability.
Runtime: 9 – 10 min.
Demo: advanced baseline open on `reqs/product.rq`; `reqs/auth.rq` exists with `login_api` and `session_policy` but `product.rq` still references them without imports — caret on a broken or unresolved link.
Related: import_from import_namespace ideaset file reference

adv_02_attributes_status_plans

reqlan rq/marketing_and_media/tutorials.rq

—

markov_chain

reqlan rq/modelling/advanced_analysis.rq

graph traveral should be tracked to inform a markov chain model of the graph.

centroid_search

reqlan rq/modelling/advanced_analysis.rq

allow user or agent to specify multiple nodes, and then to rank matches by lowest distance.

search_with_context

reqlan rq/modelling/advanced_analysis.rq

function ( exposed in cli ) that allows user to specify current contex ( set of ideas or ideasets or files ), and a search term, yielding the closest matches, in a context aware way.

pagerank

reqlan rq/modelling/advanced_analysis.rq

search algorithm

idea

reqlan rq/ontology.rq

a reqlan core unit is an idea .

ideaset

reqlan rq/ontology.rq

ideasets are namespace containers for ideas .

file

reqlan rq/ontology.rq

files store ideas and form ideasets

keyword

reqlan rq/ontology.rq

as a language , reqlan has some keywords that are reserved in some contexts .

base

reqlan rq/ontology.rq

A base is a container for ideas, ideasets, and files — the boundary of one ideas graph.
Discovery: a directory is a base only when it owns a `.reqlan` application-memory folder.
There is no implicit base from a bare workspace folder; the product prompts the user to
create `.reqlan` at the workspace-folder root when none exist.
Bases may be nested: a child directory with its own `.reqlan` is a separate base;
the parent base's index stops at that child boundary.
Each base holds its own ideas index under its `.reqlan`. Details: base.

configuration

reqlan rq/ontology.rq

There are multiples scopes for configuration . At the base level and at at the extension level .

import_statement

reqlan rq/ontology.rq

Imports are used to decribe refrences . some keyword s are reserved for imports

reference

reqlan rq/ontology.rq

References are used to link ideas to other ideas , files , and symbols .

referenced_files

reqlan rq/ontology.rq

are non rq files / ideasets that are referenced by ideas , or that reference ideas . these may be shared . they should be captured in the index

cartographic_map

reqlan rq/ontology.rq

a cartographic map is a visual representation of a graph , optimised / curated by the user for context

extension

reqlan rq/ontology.rq

the extension contains all of the actual features

grammar_rule

reqlan rq/ontology.rq

grammar rules describe the syntax features

attribute

reqlan rq/ontology.rq

attributes are for classification , functional or nonfunctional metadata .

attribute_body

reqlan rq/ontology.rq

the first attribute in an idea , if not marked otherwise , is the main ' body' attribute . It is unstructured text .

idea_name

reqlan rq/ontology.rq

the idea name is a string / handle / variable that uniquely identifies the idea ( within the ideaset / file ) . It shouldn't be a reserved keyword .

atlas

reqlan rq/ontology.rq

A challenge with navigating complex graphs is that they can be overwhelming.
One extension to the product is to have atlases

phonebook

reqlan rq/phonebook.rq

Canonical project links and publishable npm package URLs live in phonebook.json.
Modules that need contact, repo, marketplace, or npm package URLs should read from there instead of hardcoding values.
Typed access is shared via phonebook.ts for the site and extension README generator.

phonebook_icons

reqlan rq/phonebook.rq

Icon sets and lookup URLs live under the `icons` key in phonebook.json.
Each link or package icon references a set id ( `simple-icons`, `mdi`, … ) and slug `name` from that set's catalog.
Search a set at its `search` URL when renaming or replacing icons.
The site renders icons with Iconify via the packages listed in each set's `package` field per icons.rq.
Registry: phonebook-icons.ts.

npm_packages

reqlan rq/phonebook.rq

Publishable npm packages ( `@reqlan/language`, `@reqlan/analytical`, `@reqlan/cli` ) live under the `packages` key in phonebook.json.
Package ids are `language`, `analytical`, and `cli`.
The site Links section renders them under Packages per links / package_icons.
Typed helpers: `phonebookPackages`, `getPhonebookPackage` in phonebook.ts.

extension_readme_links

reqlan rq/phonebook.rq

The extension VSIX README uses phonebook link ids `site`, `github`, `vsc`, `openvsx`, and `email` for site, repository, marketplace, Open VSX, and contact URLs.
Generation is defined in extension_readme.

npm_package_readme_links

reqlan rq/phonebook.rq

Publishable npm package READMEs ( `@reqlan/language`, `@reqlan/analytical`, `@reqlan/cli` ) use the same phonebook link ids as extension_readme_links.
Generation is defined in npm_package_readme.

activity_bar_site_link

reqlan rq/phonebook.rq

The activity bar Context webview header info control opens phonebook link id `site` per info_site_link.

root_readme_links

reqlan rq/phonebook.rq

The repository README uses phonebook link ids `site`, `github`, `vsc`, `openvsx`, and `email` for site, repository, marketplace, Open VSX, and contact URLs.
Generation is defined in root_readme.

show_dont_tell

reqlan rq/ui.rq

copy should be minimal and user facing.
no long lists, no avoidable labels.

site

site/reqs/core.rq

the / site folder contains a static Next. js App Router landing page for reqlan.

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.

spec_html_export

site/reqs/core.rq

The site static build exports the workspace requirement graph ( excluding `*.secret.rq` ) under `out/spec/` via `reqlan export`.
It must pass 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_header_link pointing at the marketing site home so readers can leave the embedded spec and return to the parent site.
Pipeline: build-static.mts → export-spec.mts → verify-static-export.mts.
Host options come from html_export / CLI commands.

Status: done

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 deployment_flow.
The site workflow does not deploy on ordinary commits.
per site_distribution

pnpm

site/reqs/core.rq

Must use pnpm for all js package management.

single_page

site/reqs/core.rq

just one page.

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 cta_icon
- 404 page ( just something silly / a redirect )

tutorials_section

site/reqs/core.rq

The site exposes `/tutorials` and `/tutorials/slug/` as statically generated pages.
Catalog and deck ids come from authored 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 ).

Status: done

tutorial_location_crumb

site/reqs/core.rq

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.

Status: done

sync_presentations

site/reqs/core.rq

`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/`.

Status: done

presentation_player_route

site/reqs/core.rq

`/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.

Status: done

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.

logo

site/reqs/core.rq

- there is a logo in the sidebar.

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_url_base.

brand

site/reqs/core.rq

must be aligned with brand.rq

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.

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 )

links

site/reqs/core.rq

per phonebook
per npm_packages
Contact shows phonebook `links` then a Packages subsection for phonebook `packages`.
per link_icons
per package_icons

scope

site/reqs/icons.rq

site icon rendering for phonebook links and CTAs

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 phonebook.json per phonebook_icons.
Icons must remain compatible with static export per simple_lightweight_and_static.

phonebook_icon_keys

site/reqs/icons.rq

per phonebook_icons
Each phonebook link or package carries an `icon` object with `set` and `name`.
Set ids and lookup URLs are canonical in 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.ts: `formatPhonebookIconKey`, `getPhonebookIconSearchUrl`.

icon_registry

site/reqs/icons.rq

phonebook-icons.ts 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 phonebook.json, update the registry import for that slug.

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 globals.css.

link_icons

site/reqs/icons.rq

The contact link row in Contact.tsx renders an icon beside each phonebook link label.
per links

package_icons

site/reqs/icons.rq

The contact Packages row in Contact.tsx renders an icon beside each phonebook package label.
Package entries come from phonebook.json. packages per npm_packages.
per links

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-icons.ts via the quickstart icon set / name refs in install-actions.ts.
per components

current_link_icons

site/reqs/icons.rq

Slugs are defined on each link in 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`

showcase

site/reqs/showcase.rq

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.

Status: done

Tags: site, showcase, content

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.

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.

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.

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.

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

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.

Tags: editorial, rules

showcase_rules_set

site/reqs/showcase.rq

Ideaset (showcase_rules_set)

features_tier_1

site/reqs/showcase.rq

The reasons to adopt. All verified as shipping today.

Tags: features, tier-1

features_tier_2

site/reqs/showcase.rq

The depth. Also shipping.

Tags: features, tier-2

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.

agent_context_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: ai, mcp, planning

interlock_showcase

site/reqs/showcase.rq

Flagship. The interlock that must not fail.
A safety requirement bound to 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.

Status: done

Tags: industrial, safety, sequencing

broken_links_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: diagnostics, refactor

firmware_cloud_contract_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: integration, cross-stack, embedded

audit_trail_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: compliance, audit, export

module_surface_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: modularity, imports, ideasets

test_proves_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: testing, traceability

legacy_archaeology_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: legacy, discovery, deprecation

graph_view_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: extension, graph

attribute_dialect_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: attributes, extensibility

antipatterns_showcase

site/reqs/showcase.rq

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.

Status: done

Tags: antipattern, craft

showcase_set

site/reqs/showcase.rq

Ideaset (showcase_set)

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.

showcase_module

site/reqs/showcase.rq

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.

Status: done

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

phase_0_honesty_audit

site/reqs/showcase.rq

In parallel with content rewrite. Fix what the honesty audit surfaced.

Status: pending

Tags: tooling, honesty

phase_1_parse_gate

site/reqs/showcase.rq

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.

Status: done

phase_2_content_schema

site/reqs/showcase.rq

Extend ShowcaseBlock union and Showcase type per showcase_module.
Presentation polish can follow in phase_5_detail_layout; schema first.

Status: done

phase_3_reqs_as_truth

site/reqs/showcase.rq

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.

Status: done

phase_4_write_the_eleven

site/reqs/showcase.rq

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.

Status: done

phase_5_detail_layout

site/reqs/showcase.rq

Detail page layout: beats with captions, mechanism badges distinct from tags,
and cross-block highlighting of the shared identifier.

Status: done

phase_6_capture_media

site/reqs/showcase.rq

Capture real media from the extension for broken_links_showcase
( diagnostics / quick-fix ) and graph_view_showcase ( Cytoscape ).

Status: done

showcase_plan

site/reqs/showcase.rq

Ideaset (showcase_plan)

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.