@techierathore/techieflow 1.0.0

package/.tfcore/templates/market-research-tmpl.yaml

@@ -0,0 +1,252 @@
+template:
+  id: market-research-template-v2
+  name: Market Research Report
+  version: 2.0
+  output:
+    format: markdown
+    filename: docs/market-research.md
+    title: "Market Research Report: {{project_product_name}}"
+
+workflow:
+  mode: interactive
+  elicitation: advanced-elicitation
+  custom_elicitation:
+    title: "Market Research Elicitation Actions"
+    options:
+      - "Expand market sizing calculations with sensitivity analysis"
+      - "Deep dive into a specific customer segment"
+      - "Analyze an emerging market trend in detail"
+      - "Compare this market to an analogous market"
+      - "Stress test market assumptions"
+      - "Explore adjacent market opportunities"
+      - "Challenge market definition and boundaries"
+      - "Generate strategic scenarios (best/base/worst case)"
+      - "If only we had considered [X market factor]..."
+      - "Proceed to next section"
+
+sections:
+  - id: executive-summary
+    title: Executive Summary
+    instruction: Provide a high-level overview of key findings, market opportunity assessment, and strategic recommendations. Write this section LAST after completing all other sections.
+
+  - id: research-objectives
+    title: Research Objectives & Methodology
+    instruction: This template guides the creation of a comprehensive market research report. Begin by understanding what market insights the user needs and why. Work through each section systematically, using the appropriate analytical frameworks based on the research objectives.
+    sections:
+      - id: objectives
+        title: Research Objectives
+        instruction: |
+          List the primary objectives of this market research:
+          - What decisions will this research inform?
+          - What specific questions need to be answered?
+          - What are the success criteria for this research?
+      - id: methodology
+        title: Research Methodology
+        instruction: |
+          Describe the research approach:
+          - Data sources used (primary/secondary)
+          - Analysis frameworks applied
+          - Data collection timeframe
+          - Limitations and assumptions
+
+  - id: market-overview
+    title: Market Overview
+    sections:
+      - id: market-definition
+        title: Market Definition
+        instruction: |
+          Define the market being analyzed:
+          - Product/service category
+          - Geographic scope
+          - Customer segments included
+          - Value chain position
+      - id: market-size-growth
+        title: Market Size & Growth
+        instruction: |
+          Guide through TAM, SAM, SOM calculations with clear assumptions. Use one or more approaches:
+          - Top-down: Start with industry data, narrow down
+          - Bottom-up: Build from customer/unit economics
+          - Value theory: Based on value provided vs. alternatives
+        sections:
+          - id: tam
+            title: Total Addressable Market (TAM)
+            instruction: Calculate and explain the total market opportunity
+          - id: sam
+            title: Serviceable Addressable Market (SAM)
+            instruction: Define the portion of TAM you can realistically reach
+          - id: som
+            title: Serviceable Obtainable Market (SOM)
+            instruction: Estimate the portion you can realistically capture
+      - id: market-trends
+        title: Market Trends & Drivers
+        instruction: Analyze key trends shaping the market using appropriate frameworks like PESTEL
+        sections:
+          - id: key-trends
+            title: Key Market Trends
+            instruction: |
+              List and explain 3-5 major trends:
+              - Trend 1: Description and impact
+              - Trend 2: Description and impact
+              - etc.
+          - id: growth-drivers
+            title: Growth Drivers
+            instruction: Identify primary factors driving market growth
+          - id: market-inhibitors
+            title: Market Inhibitors
+            instruction: Identify factors constraining market growth
+
+  - id: customer-analysis
+    title: Customer Analysis
+    sections:
+      - id: segment-profiles
+        title: Target Segment Profiles
+        instruction: For each segment, create detailed profiles including demographics/firmographics, psychographics, behaviors, needs, and willingness to pay
+        repeatable: true
+        sections:
+          - id: segment
+            title: "Segment {{segment_number}}: {{segment_name}}"
+            template: |
+              - **Description:** {{brief_overview}}
+              - **Size:** {{number_of_customers_market_value}}
+              - **Characteristics:** {{key_demographics_firmographics}}
+              - **Needs & Pain Points:** {{primary_problems}}
+              - **Buying Process:** {{purchasing_decisions}}
+              - **Willingness to Pay:** {{price_sensitivity}}
+      - id: jobs-to-be-done
+        title: Jobs-to-be-Done Analysis
+        instruction: Uncover what customers are really trying to accomplish
+        sections:
+          - id: functional-jobs
+            title: Functional Jobs
+            instruction: List practical tasks and objectives customers need to complete
+          - id: emotional-jobs
+            title: Emotional Jobs
+            instruction: Describe feelings and perceptions customers seek
+          - id: social-jobs
+            title: Social Jobs
+            instruction: Explain how customers want to be perceived by others
+      - id: customer-journey
+        title: Customer Journey Mapping
+        instruction: Map the end-to-end customer experience for primary segments
+        template: |
+          For primary customer segment:
+
+          1. **Awareness:** {{discovery_process}}
+          2. **Consideration:** {{evaluation_criteria}}
+          3. **Purchase:** {{decision_triggers}}
+          4. **Onboarding:** {{initial_expectations}}
+          5. **Usage:** {{interaction_patterns}}
+          6. **Advocacy:** {{referral_behaviors}}
+
+  - id: competitive-landscape
+    title: Competitive Landscape
+    sections:
+      - id: market-structure
+        title: Market Structure
+        instruction: |
+          Describe the overall competitive environment:
+          - Number of competitors
+          - Market concentration
+          - Competitive intensity
+      - id: major-players
+        title: Major Players Analysis
+        instruction: |
+          For top 3-5 competitors:
+          - Company name and brief description
+          - Market share estimate
+          - Key strengths and weaknesses
+          - Target customer focus
+          - Pricing strategy
+      - id: competitive-positioning
+        title: Competitive Positioning
+        instruction: |
+          Analyze how competitors are positioned:
+          - Value propositions
+          - Differentiation strategies
+          - Market gaps and opportunities
+
+  - id: industry-analysis
+    title: Industry Analysis
+    sections:
+      - id: porters-five-forces
+        title: Porter's Five Forces Assessment
+        instruction: Analyze each force with specific evidence and implications
+        sections:
+          - id: supplier-power
+            title: "Supplier Power: {{power_level}}"
+            template: "{{analysis_and_implications}}"
+          - id: buyer-power
+            title: "Buyer Power: {{power_level}}"
+            template: "{{analysis_and_implications}}"
+          - id: competitive-rivalry
+            title: "Competitive Rivalry: {{intensity_level}}"
+            template: "{{analysis_and_implications}}"
+          - id: threat-new-entry
+            title: "Threat of New Entry: {{threat_level}}"
+            template: "{{analysis_and_implications}}"
+          - id: threat-substitutes
+            title: "Threat of Substitutes: {{threat_level}}"
+            template: "{{analysis_and_implications}}"
+      - id: adoption-lifecycle
+        title: Technology Adoption Lifecycle Stage
+        instruction: |
+          Identify where the market is in the adoption curve:
+          - Current stage and evidence
+          - Implications for strategy
+          - Expected progression timeline
+
+  - id: opportunity-assessment
+    title: Opportunity Assessment
+    sections:
+      - id: market-opportunities
+        title: Market Opportunities
+        instruction: Identify specific opportunities based on the analysis
+        repeatable: true
+        sections:
+          - id: opportunity
+            title: "Opportunity {{opportunity_number}}: {{name}}"
+            template: |
+              - **Description:** {{what_is_the_opportunity}}
+              - **Size/Potential:** {{quantified_potential}}
+              - **Requirements:** {{needed_to_capture}}
+              - **Risks:** {{key_challenges}}
+      - id: strategic-recommendations
+        title: Strategic Recommendations
+        sections:
+          - id: go-to-market
+            title: Go-to-Market Strategy
+            instruction: |
+              Recommend approach for market entry/expansion:
+              - Target segment prioritization
+              - Positioning strategy
+              - Channel strategy
+              - Partnership opportunities
+          - id: pricing-strategy
+            title: Pricing Strategy
+            instruction: |
+              Based on willingness to pay analysis and competitive landscape:
+              - Recommended pricing model
+              - Price points/ranges
+              - Value metric
+              - Competitive positioning
+          - id: risk-mitigation
+            title: Risk Mitigation
+            instruction: |
+              Key risks and mitigation strategies:
+              - Market risks
+              - Competitive risks
+              - Execution risks
+              - Regulatory/compliance risks
+
+  - id: appendices
+    title: Appendices
+    sections:
+      - id: data-sources
+        title: A. Data Sources
+        instruction: List all sources used in the research
+      - id: calculations
+        title: B. Detailed Calculations
+        instruction: Include any complex calculations or models
+      - id: additional-analysis
+        title: C. Additional Analysis
+        instruction: Any supplementary analysis not included in main body

package/.tfcore/templates/project-brief-tmpl.yaml

@@ -0,0 +1,221 @@
+template:
+  id: project-brief-template-v2
+  name: Project Brief
+  version: 2.0
+  output:
+    format: markdown
+    filename: docs/brief.md
+    title: "Project Brief: {{project_name}}"
+
+workflow:
+  mode: interactive
+  elicitation: advanced-elicitation
+  custom_elicitation:
+    title: "Project Brief Elicitation Actions"
+    options:
+      - "Expand section with more specific details"
+      - "Validate against similar successful products"
+      - "Stress test assumptions with edge cases"
+      - "Explore alternative solution approaches"
+      - "Analyze resource/constraint trade-offs"
+      - "Generate risk mitigation strategies"
+      - "Challenge scope from MVP minimalist view"
+      - "Brainstorm creative feature possibilities"
+      - "If only we had [resource/capability/time]..."
+      - "Proceed to next section"
+
+sections:
+  - id: introduction
+    instruction: |
+      This template guides creation of a comprehensive Project Brief that serves as the foundational input for product development.
+
+      Start by asking the user which mode they prefer:
+
+      1. **Interactive Mode** - Work through each section collaboratively
+      2. **YOLO Mode** - Generate complete draft for review and refinement
+
+      Before beginning, understand what inputs are available (brainstorming results, market research, competitive analysis, initial ideas) and gather project context.
+
+  - id: executive-summary
+    title: Executive Summary
+    instruction: |
+      Create a concise overview that captures the essence of the project. Include:
+      - Product concept in 1-2 sentences
+      - Primary problem being solved
+      - Target market identification
+      - Key value proposition
+    template: "{{executive_summary_content}}"
+
+  - id: problem-statement
+    title: Problem Statement
+    instruction: |
+      Articulate the problem with clarity and evidence. Address:
+      - Current state and pain points
+      - Impact of the problem (quantify if possible)
+      - Why existing solutions fall short
+      - Urgency and importance of solving this now
+    template: "{{detailed_problem_description}}"
+
+  - id: proposed-solution
+    title: Proposed Solution
+    instruction: |
+      Describe the solution approach at a high level. Include:
+      - Core concept and approach
+      - Key differentiators from existing solutions
+      - Why this solution will succeed where others haven't
+      - High-level vision for the product
+    template: "{{solution_description}}"
+
+  - id: target-users
+    title: Target Users
+    instruction: |
+      Define and characterize the intended users with specificity. For each user segment include:
+      - Demographic/firmographic profile
+      - Current behaviors and workflows
+      - Specific needs and pain points
+      - Goals they're trying to achieve
+    sections:
+      - id: primary-segment
+        title: "Primary User Segment: {{segment_name}}"
+        template: "{{primary_user_description}}"
+      - id: secondary-segment
+        title: "Secondary User Segment: {{segment_name}}"
+        condition: Has secondary user segment
+        template: "{{secondary_user_description}}"
+
+  - id: goals-metrics
+    title: Goals & Success Metrics
+    instruction: Establish clear objectives and how to measure success. Make goals SMART (Specific, Measurable, Achievable, Relevant, Time-bound)
+    sections:
+      - id: business-objectives
+        title: Business Objectives
+        type: bullet-list
+        template: "- {{objective_with_metric}}"
+      - id: user-success-metrics
+        title: User Success Metrics
+        type: bullet-list
+        template: "- {{user_metric}}"
+      - id: kpis
+        title: Key Performance Indicators (KPIs)
+        type: bullet-list
+        template: "- {{kpi}}: {{definition_and_target}}"
+
+  - id: mvp-scope
+    title: MVP Scope
+    instruction: Define the minimum viable product clearly. Be specific about what's in and what's out. Help user distinguish must-haves from nice-to-haves.
+    sections:
+      - id: core-features
+        title: Core Features (Must Have)
+        type: bullet-list
+        template: "- **{{feature}}:** {{description_and_rationale}}"
+      - id: out-of-scope
+        title: Out of Scope for MVP
+        type: bullet-list
+        template: "- {{feature_or_capability}}"
+      - id: mvp-success-criteria
+        title: MVP Success Criteria
+        template: "{{mvp_success_definition}}"
+
+  - id: post-mvp-vision
+    title: Post-MVP Vision
+    instruction: Outline the longer-term product direction without overcommitting to specifics
+    sections:
+      - id: phase-2-features
+        title: Phase 2 Features
+        template: "{{next_priority_features}}"
+      - id: long-term-vision
+        title: Long-term Vision
+        template: "{{one_two_year_vision}}"
+      - id: expansion-opportunities
+        title: Expansion Opportunities
+        template: "{{potential_expansions}}"
+
+  - id: technical-considerations
+    title: Technical Considerations
+    instruction: Document known technical constraints and preferences. Note these are initial thoughts, not final decisions.
+    sections:
+      - id: platform-requirements
+        title: Platform Requirements
+        template: |
+          - **Target Platforms:** {{platforms}}
+          - **Browser/OS Support:** {{specific_requirements}}
+          - **Performance Requirements:** {{performance_specs}}
+      - id: technology-preferences
+        title: Technology Preferences
+        template: |
+          - **Frontend:** {{frontend_preferences}}
+          - **Backend:** {{backend_preferences}}
+          - **Database:** {{database_preferences}}
+          - **Hosting/Infrastructure:** {{infrastructure_preferences}}
+      - id: architecture-considerations
+        title: Architecture Considerations
+        template: |
+          - **Repository Structure:** {{repo_thoughts}}
+          - **Service Architecture:** {{service_thoughts}}
+          - **Integration Requirements:** {{integration_needs}}
+          - **Security/Compliance:** {{security_requirements}}
+
+  - id: constraints-assumptions
+    title: Constraints & Assumptions
+    instruction: Clearly state limitations and assumptions to set realistic expectations
+    sections:
+      - id: constraints
+        title: Constraints
+        template: |
+          - **Budget:** {{budget_info}}
+          - **Timeline:** {{timeline_info}}
+          - **Resources:** {{resource_info}}
+          - **Technical:** {{technical_constraints}}
+      - id: key-assumptions
+        title: Key Assumptions
+        type: bullet-list
+        template: "- {{assumption}}"
+
+  - id: risks-questions
+    title: Risks & Open Questions
+    instruction: Identify unknowns and potential challenges proactively
+    sections:
+      - id: key-risks
+        title: Key Risks
+        type: bullet-list
+        template: "- **{{risk}}:** {{description_and_impact}}"
+      - id: open-questions
+        title: Open Questions
+        type: bullet-list
+        template: "- {{question}}"
+      - id: research-areas
+        title: Areas Needing Further Research
+        type: bullet-list
+        template: "- {{research_topic}}"
+
+  - id: appendices
+    title: Appendices
+    sections:
+      - id: research-summary
+        title: A. Research Summary
+        condition: Has research findings
+        instruction: |
+          If applicable, summarize key findings from:
+          - Market research
+          - Competitive analysis
+          - User interviews
+          - Technical feasibility studies
+      - id: stakeholder-input
+        title: B. Stakeholder Input
+        condition: Has stakeholder feedback
+        template: "{{stakeholder_feedback}}"
+      - id: references
+        title: C. References
+        template: "{{relevant_links_and_docs}}"
+
+  - id: next-steps
+    title: Next Steps
+    sections:
+      - id: immediate-actions
+        title: Immediate Actions
+        type: numbered-list
+        template: "{{action_item}}"
+      - id: pm-handoff
+        title: PM Handoff
+        content: |
+          This Project Brief provides the full context for {{project_name}}. Please start in 'PRD Generation Mode', review the brief thoroughly to work with the user to create the PRD section by section as the template indicates, asking for any necessary clarification or suggesting improvements.

package/.tfcore/templates/v4custom/app-agents-md-tmpl.md

@@ -0,0 +1,61 @@
+# {AppName} — project session memory (all harnesses)
+
+<!-- This file is COMMITTED (unlike CLAUDE.md, which is gitignored and imports it).
+     OpenCode and Codex auto-load AGENTS.md; Claude Code loads it through CLAUDE.md's
+     @AGENTS.md import. Keep everything in here harness-neutral — Claude-only
+     material (permissions, tool preference) lives in app-claude-md-tmpl.md. -->
+
+## Required reading before any code change
+ALWAYS read and follow:
+- **docs/{AppName}-Coding-Standards.md** — strict compliance for every line of code you write or modify.
+- **docs/{AppName}-Architecture.md** — respect module boundaries.
+- **PROJECT-STATUS.md** — for current phase & next-step context.
+
+## Hard rules (non-negotiable — the harness enforces #1)
+
+1. **Git is manual — agents NEVER run `git` or `gh`.** Not to commit, and not to read (`status`/`log`/`diff`/`grep`/`blame`). All harnesses enforce this mechanically: Claude Code via `.claude/settings.json` and `block-git.sh`; OpenCode via `opencode.jsonc` plus its plugin bridge; Codex via `.codex/rules/techieflow.rules` plus `.codex/hooks.json`. A blocked git call is the policy working, not an obstacle to route around. Evidence for status updates / "what changed" = the checklist Requirements Status table + the working-tree files (+ mtimes) + a fresh `dotnet build` (`.tfcore/tasks/_status-update-gate.md`). The OWNER commits, in a separate terminal.
+2. **Run the app yourself — the test harness is fully set up.** Headless Playwright + Chromium live in WSL; the Windows/MAUI dotnet bridge is rung #4 of the build ladder; MAUI Android/iOS/Mac Catalyst are driven over the Appium bridge (`core-config.yaml → runtimeVerification.appium`). NEVER ask the owner to boot the app, run a build, or execute a command — "can't run on Linux/WSL", "it targets Windows", "it's MAUI", "Playwright needs a GUI", "the dependent service is down" are BANNED excuses (`.tfcore/tasks/_smoke-test-policy.md`). Asking the owner is the LAST resort, only after the build ladder + `verify-phase §3a` escalation genuinely fail — and even then you still run the test yourself once they reply.
+3. **The framework tree is invisible to search — a search that finds nothing is NOT proof a file is missing.** `.tfcore/`, `.claude/`, `.codex/`, `.opencode/` and `.agents/skills/` are hidden dot-directories AND gitignored here (deliberate — deployed framework copies are never committed). File search skips hidden paths *and* honours `.gitignore`, so it takes **both** (`rg -uu`; `--hidden` alone is not enough), and `git grep`/`git ls-files` see nothing at all. Confirm a framework file by **reading its literal path** — every one has a single canonical location, and whatever needs it names that path. Never write "not present in this tree" into a verdict, a checklist Remarks cell, a BRD row, or a blocker without having tried the path and failed: that false negative propagates into the docs and the next agent treats it as fact. If a framework file really is absent, the repo needs `update-framework.sh <repo>` run once on this machine — report that instead of reimplementing what it does. (`.tfcore/tasks/_status-update-gate.md` §"The framework tree is INVISIBLE to search".)
+4. **Native-head automation binds to the app's own window.** Drive a MAUI head only through a session attached to the app under test (Windows: launched PID → its top-level window handle; Android/iOS/Catalyst: the app's package/bundle id), interact element-by-element via `AutomationId`, and NEVER inject global keyboard/mouse input — it lands in whatever window happens to have focus, not the app (`verify-phase.md §3b`).
+
+## Project basics
+- Stack: .NET 9, Blazor [Server], TrBlazeUI, [TechieRag if AI features].
+- Field-prefix convention: {obj prefix on instance fields (e.g. `private readonly ILogger<X> objLogger;`) | bare PascalCase, no prefix} — PER-PROJECT day-1 decision; this project's choice is recorded in Coding Standards §"Fields, Parameters, Locals", which is authoritative.
+- Test naming: short PascalCase, NO underscores. Full scenario in XML `<summary>` doc.
+
+## Requirement ID prefixes used in this repo
+- `REQ-UI-*` — UI work, routed to /trblazeui
+- `REQ-FN-*` — backend, routed to /flow-master
+- `REQ-RAG-*` — AI/RAG, routed to /techierag
+- `REQ-NFR-*` — non-functional
+
+Always tag work with its REQ ID in the checklist's Requirements Status **Remarks** cell (e.g. `[REQ-UI-007] settings form validation added`). Agents never git-commit (Hard rule 1); the owner's own manual commits use the same `[REQ-*]` tags.
+
+## Verification
+After every implementation phase, the verifier runs and writes per-REQ verdicts into the
+owning checklist's Requirements Status table (the single source of truth — no dated
+docs/qa files). PROJECT-STATUS.md is updated after EVERY phase (mandatory gate).
+Library issues go in the owning library's feedback file — docs/{AppName}-TrBlazeUI-Feedback.md
+or docs/{AppName}-TechieRag-Feedback.md (one file per library; each goes to its own team) —
+never silently worked around.
+
+## Slash-command syntax (READ ME if a `/agent *command` invocation fails)
+
+**Codex:** use repository skills such as `$techieflow-build`, `$techieflow-verify`, and `$techieflow-refresh-status`, or ask for the skill by name in plain language. Skills load the canonical `.tfcore/tasks/*.md` workflow. When a task calls for fan-out, delegate to the registered `tf_builder`, `tf_test_writer`, `tf_explorer`, `trblazeui`, or `techierag` Codex role and wait for its result. Defining a role alone does not authorize delegation; the user request or applicable skill must call for it. Project config and hooks require repository trust; review changed hooks with `/hooks`.
+
+**Claude Code** registers TechieFlow-native agents under the path-derived namespace `TechieFlow:agents:<name>`. The short `/<agent>` form does NOT always resolve. When in doubt use the full form:
+
+| Agent | Claude Code | OpenCode |
+|-------|-------------|----------|
+| analyst | `/TechieFlow:agents:analyst` (or `/analyst` if it resolves) | `/flow-analyst` |
+| architect | `/TechieFlow:agents:architect` | `/flow-architect` |
+| flow-master | `/TechieFlow:agents:flow-master` | `/flow-master` |
+| verifier | `/TechieFlow:agents:verifier` | `/flow-verifier` |
+| trblazeui | `/trblazeui` (NuGet-deployed to `.claude/commands/trblazeui.md`) | `/trblazeui` |
+| techierag | `/techierag` (NuGet-deployed to `.claude/commands/techierag.md`) | `/techierag` |
+
+If `/trblazeui` or `/techierag` is missing: run `dotnet build` (the NuGet target writes `.claude/commands/<lib>.md` directly), then restart the harness. Older app repos may instead hold the legacy `.claude/<lib>.md`, which `update-framework.sh` shims forward — but nothing creates that legacy path in a current app, so never treat its absence as "the library is not deployed". Resolve a persona as `.claude/commands/<lib>.md` → `.claude/<lib>.md` → `.<lib>/<Lib>-AI-Reference.md`.
+
+Under Claude Code, if `/flow-master *render-workflow-docs <App>` returns "Unknown command", use `/TechieFlow:agents:flow-master *render-workflow-docs <App>` instead. (Under OpenCode `/flow-master` is the registered agent name — there is no fuller form to fall back to.)
+
+After the agent is loaded, every TechieFlow-native agent (analyst, architect, flow-master, verifier) accepts `*command args` style invocations. trblazeui and techierag are free-form personas — normally `flow-master *build-phase <App>` calls them as sub-agents, but you can also drive them directly with prompts like `Implement REQ-UI-* from docs/<App>-Checklist.md to match the mockups in docs/mockups/.`

package/.tfcore/templates/v4custom/app-architecture-tmpl.md

@@ -0,0 +1,127 @@
+# {AppName} — Architecture
+
+**Last updated:** {YYYY-MM-DD}
+**Status:** Current (brownfield) | Target (greenfield) | Current + planned target (brownfield with structural change)
+
+<!-- AGENT-ONLY AUTHORING NOTES. Everything in this comment is an instruction to the DRAFTING
+     AGENT, not content for the document's human reader. Carry it into the generated document
+     ONLY as this HTML comment (or drop it entirely) — NEVER as visible text: the owner reads
+     the rendered HTML and must not see authoring instructions (generate-html.md strips any
+     that leaked from older templates).
+
+  DEPTH MANDATE: this is a HUMAN document, read as rendered HTML. Module rows in §4 with
+  non-trivial behavior get a prose paragraph beneath the table, and every significant runtime
+  flow beyond §3's primary path (background jobs, ingestion pipelines, auth handshakes,
+  external-API round-trips) gets its own sequenceDiagram/flowchart. When harvesting source
+  docs, preserve their architecture content — superset, never summary.
+
+  MERMAID MANDATE: every diagram MUST follow the authoring rules in
+  .tfcore/templates/v4custom/html-render-shell.md §5.5 — quote every node/edge/subgraph label
+  (API["ASP.NET API (v2)"], not API[ASP.NET API (v2)]) and never use `end` as a node id.
+  Unquoted special characters ( ( ) / & : , … ) in flowchart labels are the #1 cause of
+  "Syntax error" diagrams in the rendered HTML.
+-->
+
+## Table of Contents
+
+<!-- Auto-maintained by the analyst/day-1 tasks. Use the slug rule from .tfcore/templates/v4custom/html-render-shell.md §1 so links work in both MD and rendered HTML. Update this list whenever you add/rename a section. -->
+
+1. [Tech stack](#tech-stack)
+2. [Component map](#component-map)
+3. [Data flow — primary path](#data-flow-primary-path)
+4. [Module responsibilities](#module-responsibilities)
+5. [Cross-cutting concerns](#cross-cutting-concerns)
+6. [Deployment architecture](#deployment-architecture)
+7. [Architectural decisions (ADR-style log)](#architectural-decisions-adr-style-log)
+8. [Target architecture (brownfield only — if enhancement changes structure)](#target-architecture-brownfield-only-if-enhancement-changes-structure)
+9. [Open questions / risks](#open-questions-risks)
+
+## 1. Tech stack
+| Layer | Choice | Version | Notes |
+|-------|--------|---------|-------|
+| Runtime | .NET 9 | … | … |
+| UI | Blazor [Server/WASM/Auto] + TrBlazeUI | … | … |
+| AI/RAG | TechieRag | … | If applicable |
+| DB | SQL Server / SQLite / Postgres | … | … |
+| Vector store | SqliteVec / PgVector / Qdrant | … | If RAG |
+| Auth | … | … | … |
+
+## 2. Component map
+```mermaid
+flowchart TB
+  subgraph UI["Blazor UI"]
+    Dash["Dashboard"]
+    Settings["Settings"]
+  end
+  subgraph BE["Backend"]
+    API["API"]
+    Auth["Auth"]
+    Rag["RAG service"]
+  end
+  subgraph Data["Data"]
+    SQL[("SQL")]
+    Vec[("Vector")]
+  end
+  UI --> API
+  API --> Auth
+  API --> Rag
+  Rag --> Vec
+  API --> SQL
+```
+
+## 3. Data flow — primary path
+```mermaid
+sequenceDiagram
+  actor U
+  participant UI
+  participant API
+  participant Svc as Service
+  participant DB
+  U->>UI: action
+  UI->>API: HTTPS
+  API->>Svc: call
+  Svc->>DB: query
+  DB-->>Svc: rows
+  Svc-->>API: dto
+  API-->>UI: json
+  UI-->>U: render
+```
+
+## 4. Module responsibilities
+| Module | Responsibility | Depends on |
+|--------|----------------|------------|
+| `src/{AppName}.Web` | UI host | Domain, Infra |
+| `src/{AppName}.Domain` | Entities, business rules | (none) |
+| `src/{AppName}.Infrastructure` | EF, external services | Domain |
+| `src/{AppName}.Rag` | TechieRag wiring (if applicable) | Domain |
+
+## 5. Cross-cutting concerns
+- Logging — Serilog file-based logging (rolling file sink under `logs/`, wired at startup in EVERY executable head — web, API, MAUI, desktop, console; app code logs via `ILogger<T>`). This is a TechieFlow standing requirement, not a per-app choice — see Coding Standards §Logging.
+- Error handling — global middleware; ProblemDetails responses
+- Auth — JWT / cookie / Azure AD
+- Caching — IMemoryCache / Redis
+- Telemetry — OpenTelemetry / Application Insights
+
+## 6. Deployment architecture
+```mermaid
+flowchart LR
+  Dev["Dev"] --> CI["GitHub Actions"]
+  CI --> Reg["Container Reg"]
+  Reg --> AKS["Azure App Service / AKS"]
+  AKS --> ProdDB[("SQL")]
+```
+
+## 7. Architectural decisions (ADR-style log)
+- **ADR-001 — <decision>.** Reason: …
+- **ADR-002 — <decision>.** Reason: …
+
+## 8. Target architecture (brownfield only — if enhancement changes structure)
+```mermaid
+flowchart TB
+  Existing["existing module"] --> New["new / changed module"]
+  New --> Removed["removed box (struck through in prose)"]
+```
+Describe deltas: what's added, what's removed, what's renamed, migration path.
+
+## 9. Open questions / risks
+- …