norn-cli 2.2.2 → 2.4.0

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "WebSearch",
+      "Bash(git checkout *)",
+      "Bash(node ./dist/cli.js tests/Regression/nornenv-templates/extends-resolution.norn -s PrintResolvedValues -e prod_uk)",
+      "Bash(node ./dist/cli.js tests/Regression/nornenv-templates/extends-resolution.norn -s PrintResolvedValues -e prod_us)",
+      "Bash(node ./dist/cli.js tests/Regression/nornenv-templates/extends-resolution.norn -s PrintResolvedValues -e diamond)",
+      "Bash(node ./dist/cli.js tests/Regression/nornenv-templates/extends-resolution.norn -s PrintResolvedValues -e base)",
+      "Bash(mv .nornenv .nornenv.bak)",
+      "Bash(cp cycle.nornenv .nornenv)",
+      "Bash(timeout 10 node ../../../dist/cli.js extends-resolution.norn -s PrintResolvedValues -e c)",
+      "Bash(time node ../../../dist/cli.js extends-resolution.norn -s PrintResolvedValues -e c)",
+      "Bash(time node /Users/petercrest/Worktable/Projects/vsApi/dist/cli.js extends-resolution.norn -s PrintResolvedValues -e c)"
+    ]
+  }
+}

package/.claude/skills/norn-social-campaign/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: norn-social-campaign
+description: Continue Peter's Norn LinkedIn social-media campaign — draft/review/schedule posts, reply to engagement, evaluate Week-N kill-criteria, log community signals. Use whenever the user asks about Norn LinkedIn posts, replies, engagement metrics, the GTM experiment, what to post next, or any social/content work for Norn.
+---
+
+# Norn Social Media Campaign — Cross-Session Continuity
+
+You are resuming an ongoing GTM experiment Peter has been running for **Norn** (a commercial VS Code extension + CLI he builds solo while employed full-time, UK-based). Most strategic decisions are **locked** — your job is to execute within them, not re-litigate. The canonical state lives in repo `Docs/`; read those before doing real work.
+
+## Read these first (canonical, in this repo)
+
+- `Docs/gtm_plan.md` — **the master plan**. Locked positioning, 13-week kill-criteria with anchored dates, action steps, and an append-only **Progress Log** (scroll to the bottom to see exactly where things stand).
+- `Docs/mot_reaction_series.md` — **the LinkedIn posts** (the filename is misnamed — see Anti-patterns; rename pending).
+- `Docs/linkedin_series.md` — LinkedIn delivery rules (tags, first-comment text, image policy, posting cadence).
+- `Docs/market_signals.md` — append-only community pain-signal intel log. Append; don't re-derive.
+- `Docs/postman_rot_essay.md` (long-form v3) and `Docs/mot_series.md` (v1 micro-posts) — backup bank, not active.
+
+Memory files `norn-gtm-decision.md` and `norn-messaging-locked.md` auto-load and carry the durable decisions.
+
+## What is LOCKED — do not reopen
+
+- **Positioning spine (verbatim, never paraphrase):**
+  > Norn turns API requests into version-controlled tests your whole team can keep — authored and debugged in VS Code, run on every PR in CI.
+  Category = repo-native API regression testing. NOT "REST client", NOT vaguer "workflow automation."
+- **GTM motion:** public commercial launch (PLG + upmarket founder-led semi-sales). 13-week time-boxed experiment. Kill-criteria + anchored dates in `gtm_plan.md`. "CV-asset" is an accepted non-failure outcome.
+- **Sell to:** CTO / founding eng / tech lead at small companies (~≤20–30 people). **QA = evangelist, not buyer.** Eng Manager parked until 50+ people.
+- **Pricing model:** VS Code Extension is **free forever (incl. commercial).** CLI is **free for local use.** **Paid only for CLI Pipeline Use (CI/CD).** No evaluation period. Encoded in `LICENSE` (vsApi + Norn, kept in sync).
+- **Channel: LinkedIn only.** MoT dropped 2026-05-18. One uniform series posted to LinkedIn.
+- **Voice:** dry, specific, recognition-humor, no slang/meme/"touch grass" register, clarity > cleverness, no clever coda after the closing question. ~150–220 words per post.
+- **Canonical ending** (append verbatim, URL-free, to every post):
+  > Disclosure so nobody feels tricked: I build Norn — my attempt at the in-the-repo fix. That's the entire pitch; the post stands without it. Still genuinely curious about the question above, though.
+- **Tags (fixed, every post):** `#API #Testing #DeveloperTools`. Add `#MCP` only on the MCP post. 4 max.
+- **First comment** (within ~1 min of posting):
+  > The Norn bit I mentioned, if you want to poke at it: https://nornapi.com
+- **Posting cadence:** Tue–Thu ~8:30am UK time, one post/day, ≥4–5 days apart.
+- **Visual rule:** real source screenshot (with identifying bits cropped) if a genuine artifact exists; text-only otherwise. **Never** Norn logo. **Never** AI imagery.
+- **Self-presentation:** "QA / automation engineer who builds Norn." **Never "Founder."** The reason is strategic (credibility + disclosure-not-pitch posture), not legal — Peter's employment contract is permissive, employer has long known.
+
+## Anti-patterns — do NOT do
+
+- **Don't reopen the positioning spine.** It was rewritten many times before locking; uniformity *is* the strategy.
+- **Don't suggest pitching Peter's employer.** Internal-champion path was closed 2026-05-18 — declined "prefer not to sour the relationship" (structural/relationship objection, not product, not IP). Their "no" is excluded from any market-signal read.
+- **Don't raise the employer IP-alarm.** Contract permissive; employer long aware; Peter refused a restrictive replacement years ago specifically to protect this. Settled.
+- **Don't suggest MoT / Reddit / forums as a posting channel.** Dropped. LinkedIn only.
+- **Don't pitch Norn in post bodies or in comment replies.** The canonical ending + first comment do all the selling. Replies = host of a conversation, not salesperson.
+- **Don't suggest a separate LinkedIn-native content stream.** One uniform series. Per-channel variants caused the consistency problem the whole session was about.
+- **Don't add clever/meta codas after the closing question.** Two prior attempts ("wishful Slack message", "I want to collect these") had to be fixed because they were too clever for the reader. Plain question close, full stop.
+- **Don't suggest building product features speculatively.** Build bets in `market_signals.md` are *candidates* — build only after Week-7+ signals justify. "Don't build on spec."
+- **Don't write more posts on spec before the Week-4 verdict.** If the format doesn't travel, posts 7+ are wasted on a wrong format.
+- **The file `mot_reaction_series.md` is misnamed** (no MoT anymore). Rename to `linkedin_posts.md` is a pending cleanup; cross-refs in `gtm_plan.md` and `linkedin_series.md` will need updating in the same pass.
+
+## How to handle common requests
+
+- **"Give me the next post" / "what should I post":** check the Progress Log in `gtm_plan.md` to see which posts are scheduled vs sent. Posts live in `mot_reaction_series.md`. Format LinkedIn-ready: strip the internal `## N. Title` label; strip markdown asterisks (LinkedIn shows them literally); append the canonical ending; append the tag line; provide the first-comment text separately. Image: real cropped screenshot if a genuine source exists, otherwise text-only.
+- **"Reply to this comment":** stay in voice; *extend* the discussion, never thank generically; no Norn pitch in the reply (the bio carries it); reply **fast** — early engagement is the single biggest reach lever, far above any other tactic.
+- **"How's the post doing?" / metrics:** calibrate via ratios more than raw numbers. Comment-to-reaction ratio above ~8% = high engagement. A **Send** (LinkedIn DM forward) is the highest-value action — it's the peer-to-peer endorsement the plan was built for. Saves > likes in intent. n=1 is not a trend.
+- **"Week-N review":** open the kill-criteria table in `gtm_plan.md` (dates anchored to 2026-05-21 launch). Evaluate signals honestly against the rule. **The pre-committed exit only works if the review actually happens** — sunk cost will narrate; resist it.
+- **New community pain signal (Reddit/Lobsters/HN):** append verbatim quote + URL + date to `Docs/market_signals.md`, triage into LinkedIn angle + build-bet columns. Don't let mining displace posting.
+
+## Working style with Peter
+
+- Convert relative dates to absolute when logging (UK timezone).
+- Peter is a non-writer; he trusts drafts. When asked for content, give **clean, copy-pasteable** text. No padding, no "here you go" framing.
+- Peter values **brevity, decisiveness, and honest pushback** over compliance. If something he's about to do is wrong, say so directly with reasoning. Don't be a yes-man — he's caught me on it before.
+- **Consistency is his #1 value.** Keep the Docs as the single source of truth. Any time copy gets revised, sync everywhere it appears.
+- When in doubt about state, **read the bottom of `gtm_plan.md`'s Progress Log** — that's where the truth lives.
+
+---
+
+This skill is the index. The `Docs/` files are the canon. When in doubt, read them.

package/CHANGELOG.md

@@ -2,7 +2,28 @@
 
 All notable changes to the "Norn" extension will be documented in this file.
 
-## [Unreleased]
+## [2.4.0] - 2026-05-25
+
+### Added
+- **Per-folder and persisted active environment** — the active env is now tracked per `.nornenv` file (keyed by absolute path) and persisted to the workspace memento. In monorepos each folder remembers its own selection, and selections survive VS Code restart. The status bar shows the env for the current editor's nearest `.nornenv`. Stale entries (deleted `.nornenv` files) are pruned on load.
+- **Region-pattern refactor** — when a `.nornenv` contains a flat `[env:STAGE_REGION]` matrix (e.g. `dev_us`, `dev_uk`, `prod_us`, `prod_uk`), the top of the file shows a "Refactor N envs into S+R templates" CodeLens. Clicking it classifies each variable by axis (stage / region / leaf-specific) and lifts shared values into `[template:STAGE]` + `[template:REGION]` blocks, leaving only true leaf-specific overrides in the env sections. Missing values and `connectionString` declarations stay leaf-specific, per-declaration `secret` keywords are preserved, and the same generator is available in the CLI via `--refactor-region-pattern` / `--write`. The VS Code refactor is one `WorkspaceEdit` so a single Cmd+Z reverses it.
+
+## [2.3.0] - 2026-05-20
+
+### Added
+- **Inlay hints + hover across every Norn file type**:
+  - `.norn`: every `{{name}}` / `{{$env.name}}` token resolves under the active env, with three-scope precedence — sequence-local `var` declarations ← file-level `var` declarations ← active env's effective vars. Runtime values (`$1.body.x`, `run X()`, request captures) are intentionally not rendered inline; hover narrates them with source line.
+  - `.nornapi`: every `{{...}}` token in headers groups and endpoint definitions resolves under the active env.
+  - `.nornsql`: the `connection NAME` line shows the resolved `NAME_connectionString` from `.nornenv` (masked if a `secret connectionString`). Hover narrates the source. Any `{{...}}` in SQL bodies is handled for parity.
+  - Resolution and reference parsing live in `src/inlayHintResolver.ts` so every provider behaves identically.
+- **`.nornenv` Templates And Extends (Extension + CLI)**:
+  - Added `[template:NAME]` sections and multi-parent template `extends` on `[env:...]` / `[template:...]` headers.
+  - Resolved env values as `common <- template1 <- template2 <- self`; templates compose into envs but are not selectable in the status bar or CLI `-e`.
+  - Added `.nornenv` Activate/Deactivate and Peek inherited CodeLens actions, folding ranges, smart header decorations, hover resolution chains, inlay hints for `{{...}}`, and inherited-variable completions.
+  - Added diagnostics for unknown extends parents, invalid env parents, extends cycles, out-of-scope cross-section references, and typo-like override names.
+
+### Fixed
+- Endpoint path arguments now keep bare `.nornenv` names as literal path values unless the reference is explicit (`{{name}}` / `{{$env.name}}`), while declared file/sequence variables still resolve in endpoint calls.
 
 ## [2.2.0] - 2026-05-09
 

package/LICENSE

@@ -8,13 +8,17 @@ If you do not wish to be bound by the terms of this Agreement, you may not downl
 
 • DEFINITIONS
 
-"Authorized User" means any employee, independent contractor or other temporary worker authorized by Licensee to use the Software while performing duties within the scope of their employment or assignment.
+"Extension" means the Norn extension for Visual Studio Code.
+
+"CLI" means the Norn command-line interface.
 
-"License Key" means a unique key-code that enables a single Authorized User to use the Software at a time. Only Licensor and/or its representatives are permitted to produce License Keys for the Software.
+"Pipeline Use" means execution of the CLI within an automated build, test, integration, delivery or deployment pipeline, including but not limited to continuous integration and continuous delivery (CI/CD) systems, whether hosted or self-hosted, and whether or not triggered by a human.
 
-"Commercial Use" means any use of the Software in connection with a business, including but not limited to: (a) use by an employee or contractor during paid work hours, (b) use to develop, test, or maintain software or services that generate revenue, (c) use within a for-profit organisation, or (d) use in CI/CD pipelines for commercial projects.
+"Local Use" means execution of the CLI directly by an individual on a workstation or development machine, outside of any automated pipeline.
+
+"Authorized User" means any employee, independent contractor or other temporary worker authorized by Licensee to use the Software while performing duties within the scope of their employment or assignment.
 
-"Personal Use" means use by an individual for personal projects, learning, education, or open-source projects that do not generate revenue.
+"License Key" means a unique key-code that authorizes Pipeline Use of the CLI. Only Licensor and/or its representatives are permitted to produce License Keys for the Software.
 
 • OWNERSHIP
 
@@ -26,35 +30,22 @@ Upon your acceptance of this Agreement, Licensor grants you a limited, non-trans
 
 • INTENDED USERS OF THE SOFTWARE
 
-The Norn software is licensed to provide functionality to test APIs in Visual Studio Code as an Extension. The Norn CLI can be used locally on the user's computer for Personal Use without a license. A license is required to use the Software for Commercial Use, including use of the Norn CLI in CI/CD build pipelines.
-
-• FREE USE (PERSONAL USE)
-
-You may install and use the Software free of charge for Personal Use, including:
-- Personal projects and experimentation
-- Learning and educational purposes
-- Open-source projects that do not generate revenue
-- Academic research
-
-• COMMERCIAL EVALUATION
+The Extension is free to install and use for everyone, including individuals, businesses and organisations, for any purpose including commercial purposes, and never requires a License Key. The CLI is free for Local Use. A License Key is required only for Pipeline Use of the CLI. No License Key is required to use the Extension or to use the CLI for Local Use.
 
-Businesses and organisations may evaluate the Software for Commercial Use without a license for a period of thirty (30) days from first use ("Evaluation Period"). The Evaluation Period is:
-- Limited to one (1) evaluation period per organisation
-- Intended for genuine evaluation purposes only
-- Not to be used for production workloads or client projects
-- Not extendable or renewable without written permission from the Licensor
+• FREE USE
 
-After the Evaluation Period, continued Commercial Use requires a valid license. Abuse of the Evaluation Period, including but not limited to repeated evaluations by the same organisation, rotating users to extend evaluation, or using evaluation for production purposes, constitutes a breach of this Agreement.
+You may install and use the following free of charge, without a License Key:
+- The Extension, for any use, including commercial use within a for-profit company or organisation
+- The CLI for Local Use, including personal projects and experimentation, learning and education, academic research, and open-source projects
 
-• COMMERCIAL USE
+• LICENSED USE (PIPELINE USE OF THE CLI)
 
-A license is required for Commercial Use of the Software after the Evaluation Period. Commercial Use includes but is not limited to:
-- Use within a for-profit company or organisation
-- Use by employees or contractors during paid work
-- Use in CI/CD pipelines for commercial projects
-- Use to develop, test, or maintain revenue-generating software or services
+A valid License Key is required for any Pipeline Use of the CLI. For the avoidance of doubt:
+- The Extension never requires a License Key, including when used commercially within a for-profit company or organisation
+- Local Use of the CLI never requires a License Key
+- Only Pipeline Use of the CLI (for example, running the CLI in a CI/CD build, test, or deployment pipeline) requires a License Key
 
-Please contact the Licensor for commercial licensing options.
+Please contact the Licensor for licensing options.
 
 • RESTRICTIONS ON USE OF THE SOFTWARE
 
@@ -64,7 +55,7 @@ b) Decompile, disassemble or reverse engineer the Software or attempt to do any
 c) Reproduce, copy, distribute, resell or otherwise use the whole or any part of the Software's code for any commercial purpose.
 d) Disable, modify or hide notifications sent by the Software.
 e) Distribute, resell, or share License Keys.
-f) Misrepresent your use as Personal Use when it constitutes Commercial Use.
+f) Misrepresent Pipeline Use of the CLI as Local Use, or otherwise circumvent the License Key requirement for Pipeline Use.
 g) Use older versions of the Software to circumvent licensing requirements.
 
 • LIMITED WARRANTY AND DISCLAIMER OF WARRANTY

package/README.md

@@ -1,6 +1,6 @@
 # Norn
 
-Norn is a REST client for VS Code that keeps ad hoc requests, reusable API flows, and test automation in the same files. Write a request once, turn it into a sequence, debug it in the editor, and run the same `.norn` files from the CLI in CI.
+Norn turns API requests into version-controlled tests your whole team can keep — authored and debugged in VS Code, run on every PR in CI. Write a request once, turn it into a tested sequence, debug it with breakpoints in the editor, and run the exact same `.norn` files from the CLI in your pipeline.
 
 ### Simple API Requests
 
@@ -72,6 +72,37 @@ npm install -g norn-cli
 norn ./tests/smoke.norn -e dev
 ```
 
+## `.nornenv` Templates And Extends
+
+Use `[template:name]` sections for reusable environment building blocks, then compose selectable `[env:name]` sections with `extends`. Only templates can be extended. Templates are not selectable from the status bar or CLI; only `[env:...]` names can be used with `-e`.
+
+```nornenv
+var timeout = 30000
+
+[template:prod]
+var baseUrl = https://api.example.com
+secret apiKey = prod-key-789
+
+[template:uk]
+var dbHost = db.uk.example.com
+var bucket = data-uk
+
+[env:prod_uk extends prod, uk]
+var failoverHost = api-failover.uk.example.com
+```
+
+Resolution order is `common <- template1 <- template2 <- self`, so later templates win on collisions and the env section itself wins over everything. The VS Code editor also shows Activate CodeLens actions, inherited-variable peeks, hover resolution chains, and inlay hints for `{{name}}` / `{{$env.name}}` references.
+
+## Inlay Hints Across Every File Type
+
+Every `{{...}}` reference in any Norn file shows its resolved value as a gray inline hint under the active env, with the same masking-for-secrets rules as `.nornenv`. The three scopes available in `.norn` resolve in precedence order:
+
+1. **Sequence-local** `var` declarations inside the current `test sequence ... end sequence` block
+2. **File-level** `var` declarations at the top of the file (above any sequence)
+3. **Active env** effective vars (`common` ← ancestor templates ← self)
+
+`{{$env.name}}` always reads from scope 3, skipping local/file vars. Runtime values (`$1.body.id`, request captures, `run X()` returns) render no hint inline; hover narrates them with source line. `.nornapi` and `.nornsql` use env scope only; `.nornsql` additionally shows the resolved connection string after `connection NAME`.
+
 ## Deterministic MCP Tools
 
 Norn can call MCP tools from sequences without leaving the `.norn` runtime. MCP sessions are deterministic and shared across the full sequence run, so nested sequences reuse the same connection for the same resolved server alias.

package/demos/nornenv-region-refactor/README.md

@@ -0,0 +1,64 @@
+# Region-pattern refactor showcase
+
+A flat `[env:STAGE_REGION]` matrix that the Norn extension can refactor into the templates + extends shape in one click.
+
+## How to use
+
+1. Open [.nornenv](./.nornenv) in VS Code.
+2. A `$(sparkle) Refactor 4 envs into 2+2 templates` CodeLens appears at the top of the file.
+3. Click it. A confirmation dialog summarises what will change:
+   - 2 vars (`baseUrl`, `apiKey`) lifted to stage templates (`dev`, `prod`)
+   - 2 vars (`dbHost`, `bucket`) lifted to region templates (`us`, `uk`)
+   - 1 var (`failoverHost`) kept as leaf-specific on `prod_uk`
+4. Confirm. The flat 4-env matrix is replaced with templates + extending envs:
+
+   ```nornenv
+   [template:dev]
+       var baseUrl = https://dev.example.com
+       var apiKey = dev-key-123
+
+   [template:prod]
+       var baseUrl = https://api.example.com
+       secret apiKey = prod-key-789
+
+   [template:us]
+       var dbHost = db.us.example.com
+       var bucket = data-us
+
+   [template:uk]
+       var dbHost = db.uk.example.com
+       var bucket = data-uk
+
+   [env:dev_us extends dev, us]
+
+   [env:dev_uk extends dev, uk]
+
+   [env:prod_us extends prod, us]
+
+   [env:prod_uk extends prod, uk]
+       var failoverHost = api-failover.uk.example.com
+   ```
+
+5. The `secret` keyword on `apiKey` is preserved when the var is lifted to a template.
+
+## CLI
+
+The same generator is available from the local CLI:
+
+```bash
+node ./dist/cli.js demos/nornenv-region-refactor/.nornenv --refactor-region-pattern
+node ./dist/cli.js demos/nornenv-region-refactor/.nornenv --refactor-region-pattern --write
+```
+
+## When the refactor fires
+
+The CodeLens appears only when **all** of these are true:
+- At least 2 stages × 2 regions
+- At least 3 populated cells
+- All matrix envs are flat (no existing `extends` clause)
+
+It does not touch envs that already use `extends`, envs with names that don't match the `STAGE_REGION` shape, or `connectionString` declarations (those are left in their leaves — refactor manually).
+
+## Cmd+Z
+
+Everything goes through a single `WorkspaceEdit`, so a single Cmd+Z undoes the whole refactor.

package/demos/nornenv-showcase/README.md

@@ -0,0 +1,62 @@
+# `.nornenv` Feature Showcase
+
+A single `.nornenv` that touches every feature we've shipped — templates, multi-parent `extends`, diamond inheritance, secrets, connection-string templates, imports, plus every diagnostic. Open [.nornenv](./.nornenv) in VS Code and the editor experience does most of the talking.
+
+## What to try, in order
+
+1. **Open the file.** Non-active sections auto-collapse to one line; the smart header chips show `extends X, Y · N vars · K inherited · M overrides` plus any warning pills.
+2. **Click `▶ Activate` on `[env:prod_eu]`.** It's the most feature-dense env. Watch the file change:
+   - The `ACTIVE` pill appears on its header
+   - A brand-gradient marker shows up in the gutter on its line
+   - A teal tick appears on the right-side overview ruler
+   - Every `{{...}}` reference in the file gets an inlay hint with the now-resolved value
+   - Secrets render as `(secret)` rather than the raw value
+3. **Hover anything** — a variable name on the left side of a `=`, or a `{{ref}}`. The hover shows the resolution chain: where it's defined, whether it was inherited, and the current resolved value.
+4. **Try `▶ Peek inherited`** on a leaf env like `[env:prod_eu]` — a quick-pick lists all 8+ inherited variables with their source templates and resolved values.
+5. **Type `var ` inside `[env:prod_eu]`** — IntelliSense suggests every inherited variable name, so you can pick one to override without retyping.
+6. **Start a new section header `[`** — completion offers both `[env:` and `[template:`. After typing `[env:foo `, completion offers `extends`, then suggests every available template as a parent.
+7. **Scroll to the bottom** — the diagnostics-only block deliberately triggers every linter check:
+   - `[env:bad_unknown_parent extends prdo, us]` — `prdo` squiggles as `unknown-extends-parent` with a quick-fix suggesting `prod`
+   - `var apiKy = oops-typo` — squiggles as `unknown-override-target` with a suggestion
+   - `var dangling = {{kmsKey}}` — squiggles as `unresolved-cross-section-ref`
+   - `[env:bad_env_parent extends prod_us]` — `prod_us` squiggles as `extends-env-parent`
+   - `[template:loop_a]` / `[template:loop_b]` — both squiggle as `extends-cycle`
+
+## What to try at the CLI
+
+After `npm run compile`, run [showcase.norn](./showcase.norn) which prints every resolved value.
+
+> **Heads-up about `{{…}}` inside `.nornenv` values:** the IDE's inlay hints show the **fully recursively resolved** form (e.g. `apiBase → "https://api.prod.example.com/v2"` under `prod_eu`). The `.norn` runtime substitution is single-level — when you print `{{apiBase}}` from a `.norn` file, you'll see the literal `https://api.{{stageHost}}.example.com/{{apiVersion}}` because `apiBase`'s *value* still contains template tokens. That's standard Norn behavior — switch to the IDE for the deep view, or use leaf vars (stageHost, region, dbHost, …) for clean CLI prints.
+
+```bash
+# Most feature-dense env (self-override + diamond touchpoints).
+node ./dist/cli.js demos/nornenv-showcase/showcase.norn -e prod_eu
+
+# Right-most-wins demo — prod_strict (rightmost prod-chain template) wins on collisions.
+node ./dist/cli.js demos/nornenv-showcase/showcase.norn -e prod_eu_strict
+
+# Diamond inheritance — shared ancestor merged once.
+node ./dist/cli.js demos/nornenv-showcase/showcase.norn -e diamond
+
+# Templates are not selectable — this should error and list only env names.
+node ./dist/cli.js demos/nornenv-showcase/showcase.norn -e prod
+```
+
+## What each section demonstrates
+
+| Section | Feature |
+| --- | --- |
+| `import "./shared/.nornenv"` | Multi-file composition; chained imports merge into common |
+| top-of-file `var ...` | Common variables (shared by every env) |
+| `var apiBase = https://api.{{stageHost}}…` | Common values may reference any name — resolves under the active env |
+| `[template:dev/staging/prod]` | Stage building blocks (not selectable) |
+| `[template:prod_strict extends prod]` | Template extending another template (chained) |
+| `[template:us/eu]` | Region building blocks |
+| `[template:db_main]` with `connectionString` + `secret connectionString` | Connection-string templates, plain and secret |
+| `[env:dev_us extends dev, us, db_main]` | Composing 3 templates into one selectable env |
+| `[env:prod_eu] ... var logLevel = error` | Self-override wins over every parent |
+| `[env:prod_eu_strict extends prod_strict, eu, db_main]` | Right-most parent wins on collisions |
+| `[env:diamond extends dev, prod_strict]` | Diamond: shared ancestor merged once |
+| `[env:bad_unknown_parent ...]` | Unknown parent + typo override + dangling ref diagnostics |
+| `[env:bad_env_parent extends prod_us]` | Env-as-parent diagnostic |
+| `[template:loop_a/loop_b]` | Cycle diagnostic |

package/demos/nornenv-showcase/norn.config.json

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "sql": {
+    "connections": {
+      "main": {
+        "adapter": "showcase-fake-adapter",
+        "profile": "main"
+      }
+    },
+    "adapters": {
+      "showcase-fake-adapter": {
+        "command": ["node", "-e", "process.stderr.write('showcase: SQL adapter not wired; this file is a visual demo only.\\n'); process.exit(1);"]
+      }
+    }
+  }
+}

package/demos/nornenv-showcase/showcase.norn

@@ -0,0 +1,70 @@
+# Showcase .norn — exercises the inlay hints + hover from src/nornInlayHintsProvider
+# and src/nornHoverProvider across all three scopes:
+#   1. Sequence-local `var` declarations inside a `test sequence ... end sequence` block
+#   2. File-level `var` declarations (above any sequence)
+#   3. Active .nornenv environment (common + ancestor templates + self)
+#
+# Open this file with [env:prod_eu] active to watch every {{...}} reference
+# resolve inline; hover any reference for the source + value resolution chain.
+#
+# CLI verification:
+#   node ./dist/cli.js demos/nornenv-showcase/showcase.norn -s ShowcaseResolvedValues -e prod_eu
+#   node ./dist/cli.js demos/nornenv-showcase/showcase.norn -s ShowcaseResolvedValues -e prod_eu_strict
+#   node ./dist/cli.js demos/nornenv-showcase/showcase.norn -s ShowcaseResolvedValues -e diamond
+
+# ─── File-level vars (scope 2) ──────────────────────────────────────────────
+# These reference env vars defined in showcase.nornenv ({{region}}, {{apiVersion}}).
+# Inlay hints should resolve them recursively under the active env.
+var siteTag        = "showcase-{{region}}"
+var docsHomepage   = "{{apiBase}}/help"
+
+# ─── Sequence 1: print every resolved env-level value ───────────────────────
+test sequence ShowcaseResolvedValues
+    print "apiBase"        | "{{apiBase}}"
+    print "dataBucket"     | "{{dataBucket}}"
+    print "docsUrl"        | "{{docsUrl}}"
+    print "stageHost"      | "{{stageHost}}"
+    print "region"         | "{{region}}"
+    print "dbHost"         | "{{dbHost}}"
+    print "logLevel"       | "{{logLevel}}"
+    print "retries"        | "{{retries}}"
+    print "orgName"        | "{{orgName}}"
+    print "main_connectionString"    | "{{main_connectionString}}"
+    print "reports_connectionString" | "{{reports_connectionString}}"
+    print "apiKey"         | "{{apiKey}}"
+end sequence
+
+# ─── Sequence 2: demonstrate all three scopes in one place ──────────────────
+test sequence ShowcaseScopeLayers
+    # File-level var (scope 2) referenced from inside a sequence
+    print "siteTag"        | "{{siteTag}}"
+    print "docsHomepage"   | "{{docsHomepage}}"
+
+    # Sequence-local var (scope 1) — static value
+    var greeting           = "Hello from {{stageHost}}"
+    print "greeting"       | "{{greeting}}"
+
+    # Sequence-local var (scope 1) — composes env + region
+    var fullUserUrl        = "{{apiBase}}/{{region}}/users"
+    print "fullUserUrl"    | "{{fullUserUrl}}"
+
+    # Sequence-local var (scope 1) — overrides a file-level name within this sequence
+    var siteTag            = "scoped-override-{{stageHost}}"
+    print "siteTag (local override)" | "{{siteTag}}"
+
+    # Explicit env-only reference — bypasses local/file scope, reads directly from env
+    print "env-only region" | "{{$env.region}}"
+end sequence
+
+# ─── Sequence 3: runtime vars are intentionally NOT shown by inlay hints ────
+test sequence ShowcaseRuntimeRefs
+    # Sequence-local but RUNTIME (response capture) — no inlay hint expected on {{traceId}}.
+    # Hover on the reference will narrate "runtime expression" with source line.
+    GET https://httpbin.org/uuid
+    assert $1.status == 200
+    var traceId            = $1.body.uuid
+    print "traceId"        | "{{traceId}}"
+
+    # Response refs like {{$1.body.uuid}} are also runtime-only — no inlay hint.
+    print "uuid"           | "{{$1.body.uuid}}"
+end sequence

package/demos/nornenv-showcase/showcase.nornapi

@@ -0,0 +1,26 @@
+# Showcase .nornapi — every {{...}} on this file resolves under the active env via
+# the inlay hints from src/nornapiInlayHintsProvider.ts. Hover any reference for
+# the resolution chain.
+#
+# Try: activate [env:prod_eu] from showcase.nornenv and watch the URLs/headers
+# below resolve to prod_eu's effective values.
+
+headers Standard
+Content-Type: application/json
+Accept: application/json
+end headers
+
+headers AuthHeaders
+Authorization: Bearer {{apiKey}}
+X-Region: {{region}}
+X-Stage: {{stageHost}}
+X-Api-Version: {{apiVersion}}
+end headers
+
+endpoints
+    HealthCheck:    GET {{apiBase}}/health
+    ListCustomers:  GET {{apiBase}}/customers?region={{region}}
+    GetCustomer:    GET {{apiBase}}/customers/{customerId}
+    CreateOrder:    POST {{apiBase}}/orders
+    Failover:       GET {{failoverHost}}/status
+end endpoints

package/demos/nornenv-showcase/showcase.nornsql

@@ -0,0 +1,20 @@
+# Showcase .nornsql — the `connection main` line below is resolved by
+# src/nornsqlInlayHintsProvider.ts to `main_connectionString` from the
+# nearest .nornenv. Hover the identifier `main` to see where it's defined
+# in [template:db_main] and what it resolves to under the active env.
+#
+# Try: activate [env:prod_eu] and watch the inlay after `main` show the
+# resolved Server=tcp:db.eu.example.com,1433;... connection string.
+
+connection main
+
+query ListBuyers(region)
+select Id, Company, Email
+from Buyers
+where Region = :region
+end query
+
+command RecordAuditEntry(actor, action)
+insert into Audit (Actor, Action, At)
+values (:actor, :action, current_timestamp)
+end command