fix(docs): refine tech stack documents for clarity and specificity

templates/prompts/TECH_STACK_DISCOVERY_PROMPT.txt

@@ -1,213 +1,68 @@
-Assume PRODUCT_SPEC.md already exist and are correct.
+Input: PRODUCT_SPEC.md only. It is correct and final.
+ARCHITECTURE.md does not exist yet. It will be written AFTER TECH_STACK.md.
+
+PURPOSE
+Discover every technology decision required to generate TECH_STACK.md.
+Do NOT generate TECH_STACK.md. Do NOT generate code.
+
+SCOPE
+- The goal is technology decisions. Architecture may be discussed ONLY to
+  the extent it constrains or drives a technology choice
+  (e.g. offline-first, server presence, realtime sync, single binary).
+- Ask about architectural DRIVERS (requirements that affect the stack),
+  never about architectural SOLUTIONS (components, layers, module boundaries,
+  data flow, ownership boundaries).
+- If I propose a structural idea, do not decide it. Record it as an ARCH NOTE
+  and continue.
+- Directory, state, and dependency questions are limited to what the chosen
+  stack or framework mandates.
+
+PROCESS
+- Ask one decision at a time. Wait for the answer before continuing.
+- Never infer, assume defaults, or batch unrelated decisions.
+- If PRODUCT_SPEC.md already answers a decision, mark it ALREADY DECIDED
+  with the quoted source line, and move on.
+- If an area does not apply, mark it N/A with a one-line reason, and move on.
+- Do not evaluate or recommend technologies. Exception: if I explicitly ask
+  for a recommendation on the current question, answer only that, then
+  return to discovery mode.
+- If a later answer conflicts with a DECIDED item, stop and ask which one
+  wins before continuing.
+
+AREAS (in this order)
+1. Platform (target platforms, runtime constraints, distribution targets)
+2. Performance constraints (latency, throughput, memory)
+3. Programming language
+4. UI tech stack
+5. Rendering (approach, graphics constraints)
+6. State management (stack-level mutation model only)
+7. Persistence (storage technology and requirements)
+8. Dependency policy (external dependency rules only)
+9. Testing (test types, coverage expectations)
+10. Configuration (env separation, secret storage)
+11. Logging (rules, sensitive information)
+12. Security (secret handling, input validation)
+13. Build (variants, constraints)
+14. Deployment (targets, release environments)
+15. Debugging / observability
+
+OUTPUT FORMAT for each question:
 
-The purpose of this task is NOT to generate TECH_STACK.md.
-
-The purpose is to discover every implementation decision required to generate TECH_STACK.md.
-
-Do not infer missing decisions.
-
-Do not assume defaults.
-
-Do not recommend technologies unless explicitly asked.
-
-Do not generate TECH_STACK.md.
-
-Do not generate code.
-
-Do not evaluate alternatives unless explicitly requested.
-
----
-
-Your job is to identify implementation decisions that are still undefined.
-
-For each missing decision:
-
-- explain why the decision is required,
-- explain which parts of the system depend on it,
-- ask a question,
-- wait for an answer.
-
-Do not continue past unanswered decisions.
-
-Do not batch unrelated decisions.
-
-Ask one decision at a time.
-
-Do not make assumptions.
-
----
-
-The discovery process must cover:
-
-## Platform
-
-Determine:
-
-- target platforms
-- runtime constraints
-- distribution targets
-
----
-
-## Programming Language
-
-Determine:
-
-- implementation language
-
----
-
-## UI Tech stack
-
-Determine:
-
-- user interface tech stack
-
----
-
-## Rendering System
-
-Determine:
-
-- rendering approach
-- graphics constraints
-
----
-
-## State Management Style
-
-Determine:
-
-- state ownership model
-- mutation model
-
----
-
-## Persistence
-
-Determine:
-
-- persistence requirements
-- storage boundaries
-
----
-
-## Directory Structure
-
-Determine:
-
-- project organization rules
-- ownership boundaries
-
----
-
-## Dependency Rules
-
-Determine:
-
-- external dependency policy
-- dependency ownership
-
----
-
-## Testing
-
-Determine:
-
-- required test types
-- coverage expectations
-
----
-
-## Configuration
-
-Determine:
-
-- configuration ownership
-- environment separation rules
-
----
-
-## Logging
-
-Determine:
-
-- logging rules
-- sensitive information rules
-
----
-
-## Security
-
-Determine:
-
-- secret handling rules
-- input validation rules
-
----
-
-## Deployment
-
-Determine:
-
-- deployment targets
-- release environments
-
----
-
-## Build Rules
-
-Determine:
-
-- build variants
-- build constraints
-
----
-
-## Performance Constraints
-
-Determine:
-
-- latency requirements
-- throughput requirements
-- memory constraints
-
----
-
-## Debugging
-
-Determine:
-
-- debugging capabilities
-- observability requirements
-
----
-
-Output format:
-
-```text
 MISSING DECISION
+Name: <name>
+Reason: <why required>
+Affected Areas: <list>
+Question: <single question>
+WAITING FOR ANSWER
 
-Name:
-<decision name>
-
-Reason:
-<why this decision is required>
-
-Affected Areas:
-- ...
-
-Question:
-<single question>
+After every answer, print both logs before the next question:
 
-WAITING FOR ANSWER
-```
+DECIDED
+- <name>: <answer>
 
-Rules:
+ARCH NOTES (non-binding, for ARCHITECTURE.md later)
+- <driver or structural idea mentioned, with the decision it relates to>
 
-- Ask only one question at a time.
-- Never assume missing decisions.
-- Never generate TECH_STACK.md.
-- Never generate code.
-- Never continue automatically.
-- Wait after every answer.
+COMPLETION
+When all areas are resolved, print the final DECIDED log and ARCH NOTES,
+then stop. Do not generate TECH_STACK.md.

templates/prompts/TECH_STACK_PROMPT.txt

@@ -1,40 +1,48 @@
 Generate TECH_STACK.md.
 
-Assume PRODUCT.md and architecture.md already exist and are correct.
-
-The purpose of TECH_STACK.md is to eliminate implementation ambiguity.
-
-TECH_STACK.md defines implementation constraints only.
-
-Do not infer undecided technologies.
-
-Do not assume technology decisions have already been made.
-
-If required decisions are missing, stop and ask questions.
-
-Do not evaluate alternatives.
-
-Do not recommend technologies.
-
-When a decision has already been made, encode it as a rule.
-
-When a decision has not been made, do not invent one.
-
-The document must include:
-
-- implementation rules
-- architectural constraints
-- directory structure
-- testing rules
-- deployment rules
-- configuration rules
-- security rules
-- tech-stack-specific conventions
-- non-goals
-- architectural invariants
-
-Prefer explicit constraints over explanations.
-
-Optimize for implementation consistency.
-
-The document is intended for AI implementation, not human learning.
+INPUTS
+- PRODUCT_SPEC.md: correct and final. Source of product requirements.
+- TECH_DECISIONS: correct and final. Sole source of technology names and versions.
+- ARCHITECTURE.md does not exist yet. It will be written AFTER this document, using it as input.
+
+SOURCE RULES
+- Every technology, tool, library, version, file name, and env var name MUST come from TECH_DECISIONS.
+- MUST NOT infer, invent, evaluate, or recommend technologies.
+- MUST NOT restate product behavior from PRODUCT_SPEC (commands, options, sorting, error cases).
+- If TECH_DECISIONS conflicts with PRODUCT_SPEC, stop and list the conflicts.
+
+REQUIRED DECISIONS CHECK
+Verify TECH_DECISIONS defines all of the following. For each missing item, ask one question.
+- runtime + version
+- language + compile/run method
+- module system
+- package manager + lockfile
+- web framework + version
+- libraries (name + version): config parser, CLI argument parser, YouTube API client/HTTP
+- test tool + coverage threshold
+- linter, formatter
+- CI system
+- deployment target + release/distribution method
+- license
+- config file format, env var names, secret storage
+If any item is missing or conflicting: output ONLY the numbered question list. Nothing else.
+
+SCOPE BOUNDARY
+- Cover only technology choices and the rules that follow from them.
+- MUST NOT define components, layers, modules, boundaries, data flow, responsibilities, or system structure.
+- MUST NOT define directory layout beyond paths mandated by the chosen framework or tooling.
+- MUST NOT include process rules (change control), product non-goals, or architectural invariants.
+- State each rule once. MUST NOT repeat a rule across sections.
+
+OUTPUT FORMAT
+- Exactly these 8 sections, in this order, numbered headings, no other sections:
+  1. Languages / runtimes / frameworks / libraries (name + version constraint)
+  2. Framework- or tool-mandated paths and file names only
+  3. Coding conventions specific to the chosen stack
+  4. Testing rules (tools, naming, required coverage)
+  5. Configuration rules (env vars, config files, secrets handling)
+  6. Deployment rules (targets, build, release steps)
+  7. Security rules tied to the chosen stack
+  8. Non-goals (technologies and tools explicitly excluded)
+- Flat terse bullets. "MUST / MUST NOT" phrasing. No prose, no explanations, no "why".
+- Audience: AI implementer.

tests/index.e2e.ts

@@ -171,7 +171,7 @@ test('loads the search interface', async ({ page }) => {
 test('shows all Showcase projects as compatible cards', async ({ page }) => {
   await page.goto('/showcase');
 
-  await expect(page.locator('article a[href^="/showcase/"]')).toHaveCount(7);
+  await expect(page.locator('article a[href^="/showcase/"]')).toHaveCount(8);
 });
 
 test('keeps primary pages within a mobile viewport', async ({ page }) => {