forgedev 1.2.0 → 1.4.0

package/templates/claude-code/skills/git-workflow/SKILL.md

@@ -5,10 +5,10 @@ description: Git branching, commits, PR workflow, and conflict resolution patter
 
 ## Branching Strategy
 
-- `main` — production-ready code, never commit directly
-- `feat/<name>` — new features, branch from main
-- `fix/<name>` — bug fixes, branch from main
-- `chore/<name>` — maintenance, config changes, dependency updates
+- `main` - production-ready code, never commit directly
+- `feat/<name>` - new features, branch from main
+- `fix/<name>` - bug fixes, branch from main
+- `chore/<name>` - maintenance, config changes, dependency updates
 
 Always create a feature branch before starting work:
 ```bash
@@ -59,6 +59,6 @@ If rebase gets messy: `git rebase --abort` and start over.
 
 - Never force-push to `main`
 - Never commit `.env` files, credentials, or large binaries
-- Never rebase shared branches (`main`, `develop`) — only rebase your own feature branches
+- Never rebase shared branches (`main`, `develop`). Only rebase your own feature branches
 - Update feature branches with `git rebase origin/main`, not `git merge main` (force-push your branch after)
 - Always pull before pushing: `git pull --rebase` (pulls current branch's upstream)

package/templates/claude-code/skills/nextjs/SKILL.md

@@ -33,7 +33,7 @@ description: Next.js 15 App Router patterns and best practices
 - Intercepting routes `(.)` for modals
 
 ## Common Mistakes
-- Avoid Client Components with `useEffect` for data fetching — prefer async Server Components instead
+- Avoid Client Components with `useEffect` for data fetching. Prefer async Server Components instead
 - Don't pass functions as props from Server to Client Components
 - Don't use `router.push` when `<Link>` works
 - Don't create API routes for data that Server Components can fetch directly

package/templates/claude-code/skills/playwright/SKILL.md

@@ -12,11 +12,11 @@ description: Playwright E2E testing patterns and best practices
 - Use page object pattern for complex pages
 
 ## Selector Priority
-1. `getByRole()` — buttons, links, headings (best for accessibility)
-2. `getByLabel()` — form inputs by label
-3. `getByText()` — visible text content
-4. `getByTestId()` — `data-testid` attributes (last resort)
-- Avoid CSS selectors or XPath — they break when styles change
+1. `getByRole()`: buttons, links, headings (best for accessibility)
+2. `getByLabel()`: form inputs by label
+3. `getByText()`: visible text content
+4. `getByTestId()`: `data-testid` attributes (last resort)
+- Avoid CSS selectors or XPath. They break when styles change
 
 ## Assertions
 - Use `expect(locator)` for element assertions

package/templates/claude-code/skills/security-api/SKILL.md

@@ -20,7 +20,7 @@ description: API security best practices
 - Validate file uploads (size, type, extension)
 
 ## SQL Injection Prevention
-- Use SQLAlchemy ORM — never raw SQL strings
+- Use SQLAlchemy ORM. Never raw SQL strings
 - If raw SQL needed, use `text()` with bound parameters
 - Never interpolate user input into queries
 

package/templates/claude-code/skills/security-web/SKILL.md

@@ -6,7 +6,7 @@ description: Web application security best practices
 # Web Application Security
 
 ## XSS Prevention
-- React escapes by default — never use `dangerouslySetInnerHTML`
+- React escapes by default. Never use `dangerouslySetInnerHTML`
 - Sanitize user input before rendering
 - Use Content Security Policy headers
 - Validate URLs before using in `href` or `src`

package/templates/claude-code/skills/testing-patterns/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: testing-patterns
-description: Universal testing principles — test pyramid, AAA pattern, mocking strategies, and coverage targets
+description: Universal testing principles - test pyramid, AAA pattern, mocking strategies, and coverage targets
 ---
 
 ## Test Pyramid
 
 ```
-        /  E2E  \        — Few, slow, high confidence
-       / Integration \   — Some, medium speed
-      /    Unit Tests   \— Many, fast, focused
+        /  E2E  \        - Few, slow, high confidence
+       / Integration \   - Some, medium speed
+      /    Unit Tests   \- Many, fast, focused
 ```
 
 - **Unit tests** (70%): Test individual functions in isolation. Fast, many.
@@ -21,14 +21,14 @@ Every test follows this structure:
 
 ```
 test('should calculate total with tax', () => {
-  // Arrange — set up test data
+  // Arrange: set up test data
   const items = [{ price: 10 }, { price: 20 }];
   const taxRate = 0.1;
 
-  // Act — execute the function
+  // Act: execute the function
   const total = calculateTotal(items, taxRate);
 
-  // Assert — verify the result
+  // Assert: verify the result
   expect(total).toBe(33);
 });
 ```
@@ -52,7 +52,7 @@ test('should calculate total with tax', () => {
 
 | What | When to Mock |
 |------|-------------|
-| External APIs | Always — they're slow and unreliable |
+| External APIs | Always. They're slow and unreliable |
 | Database | Integration tests use real DB, unit tests mock |
 | Time/Date | When testing time-dependent logic |
 | File system | When testing file operations |
@@ -84,7 +84,7 @@ Use descriptive names that explain the scenario:
 
 - **80% minimum** for all code
 - **100% required** for: auth logic, financial calculations, security-critical code
-- Coverage measures lines hit, not correctness — high coverage with weak assertions is useless
+- Coverage measures lines hit, not correctness. High coverage with weak assertions is useless
 - Focus on meaningful assertions, not just line coverage
 
 ## Common Anti-Patterns

package/templates/database/prisma-postgres/{.env.example → .env.example.template}

@@ -1 +1,2 @@
+# Local development only. Change credentials before deploying to production.
 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/{{PROJECT_NAME_SNAKE}}"

package/templates/database/sqlalchemy-postgres/{.env.example → .env.example.template}

@@ -1,2 +1,3 @@
+# Local development only. Change credentials before deploying to production.
 DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/{{PROJECT_NAME_SNAKE}}"
 JWT_SECRET_KEY="change-me-generate-a-random-secret"

package/templates/docs-portal/fastapi/backend/app/portal/docs_reader.py

@@ -0,0 +1,201 @@
+"""Reads and organizes markdown files from the docs/ directory."""
+
+import logging
+from datetime import datetime
+from pathlib import Path
+from dataclasses import dataclass, field
+
+import bleach
+import markdown
+
+logger = logging.getLogger(__name__)
+
+DOCS_ROOT = Path(__file__).resolve().parent.parent.parent.parent / "docs"
+
+ALLOWED_HTML_TAGS = [
+    "a",
+    "p",
+    "ul",
+    "ol",
+    "li",
+    "strong",
+    "em",
+    "code",
+    "pre",
+    "blockquote",
+    "hr",
+    "br",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "table",
+    "thead",
+    "tbody",
+    "tr",
+    "th",
+    "td",
+]
+ALLOWED_HTML_ATTRIBUTES = {
+    "a": ["href", "title"],
+    "th": ["align"],
+    "td": ["align"],
+}
+ALLOWED_PROTOCOLS = ["http", "https", "mailto"]
+
+CATEGORY_META: dict[str, dict] = {
+    "prd": {"label": "Product", "description": "Product requirements and roadmap", "icon": "📋", "order": 1},
+    "sdd": {"label": "Architecture", "description": "System design and technical architecture", "icon": "🏗️", "order": 2},
+    "uat": {"label": "Testing", "description": "Test plans, results, and acceptance criteria", "icon": "✅", "order": 3},
+    "sessions": {"label": "Session Logs", "description": "Testing session results and bug reports", "icon": "📝", "order": 4},
+}
+
+
+@dataclass
+class DocFile:
+    slug: str
+    title: str
+    content: str
+    html: str
+    category: str
+    category_label: str
+    last_modified: datetime
+
+
+@dataclass
+class DocCategory:
+    id: str
+    label: str
+    description: str
+    icon: str
+    order: int
+    docs: list[dict] = field(default_factory=list)
+
+
+def _extract_title(content: str, filename: str) -> str:
+    for line in content.split("\n"):
+        line = line.strip()
+        if line.startswith("# ") and not line.startswith("##"):
+            return line[2:].strip()
+    return filename.replace(".md", "").replace("-", " ").replace("_", " ").title()
+
+
+def _render_markdown(content: str) -> str:
+    md = markdown.Markdown(extensions=["tables", "fenced_code", "toc"])
+    html = md.convert(content)
+    return bleach.clean(
+        html,
+        tags=ALLOWED_HTML_TAGS,
+        attributes=ALLOWED_HTML_ATTRIBUTES,
+        protocols=ALLOWED_PROTOCOLS,
+        strip=True,
+    )
+
+
+def get_categories() -> list[DocCategory]:
+    if not DOCS_ROOT.exists():
+        return []
+
+    categories: list[DocCategory] = []
+
+    for entry in sorted(DOCS_ROOT.iterdir()):
+        if not entry.is_dir():
+            continue
+
+        category_id = entry.name
+        meta = CATEGORY_META.get(category_id, {
+            "label": category_id.capitalize(),
+            "description": "",
+            "icon": "📄",
+            "order": 99,
+        })
+
+        md_files = sorted(entry.glob("*.md"))
+        if not md_files:
+            continue
+
+        docs = []
+        for f in md_files:
+            try:
+                content = f.read_text(encoding="utf-8")
+                docs.append({
+                    "slug": f.stem,
+                    "title": _extract_title(content, f.name),
+                })
+            except (OSError, UnicodeDecodeError) as exc:
+                logger.warning("Skipping docs file %s: %s", f.name, exc)
+                continue
+
+        categories.append(DocCategory(
+            id=category_id,
+            label=meta["label"],
+            description=meta["description"],
+            icon=meta["icon"],
+            order=meta["order"],
+            docs=docs,
+        ))
+
+    # Top-level markdown files
+    top_level = sorted(DOCS_ROOT.glob("*.md"))
+    if top_level:
+        docs = []
+        for f in top_level:
+            content = f.read_text(encoding="utf-8")
+            docs.append({
+                "slug": f.stem,
+                "title": _extract_title(content, f.name),
+            })
+        categories.append(DocCategory(
+            id="_general",
+            label="General",
+            description="Project documentation",
+            icon="📄",
+            order=99,
+            docs=docs,
+        ))
+
+    return sorted(categories, key=lambda c: c.order)
+
+
+def get_doc(category: str, slug: str) -> DocFile | None:
+    if category == "_general":
+        file_path = DOCS_ROOT / f"{slug}.md"
+    else:
+        file_path = DOCS_ROOT / category / f"{slug}.md"
+
+    # Prevent path traversal — resolved path must stay within DOCS_ROOT
+    docs_root_resolved = DOCS_ROOT.resolve()
+    resolved = file_path.resolve()
+    try:
+        resolved.relative_to(docs_root_resolved)
+    except ValueError:
+        return None
+
+    if not resolved.exists():
+        return None
+
+    content = resolved.read_text(encoding="utf-8")
+    stat = resolved.stat()
+    meta = CATEGORY_META.get(category, {"label": "General"})
+
+    return DocFile(
+        slug=slug,
+        title=_extract_title(content, f"{slug}.md"),
+        content=content,
+        html=_render_markdown(content),
+        category=category,
+        category_label=meta["label"],
+        last_modified=datetime.fromtimestamp(stat.st_mtime),
+    )
+
+
+def get_all_docs() -> list[DocFile]:
+    docs: list[DocFile] = []
+    for cat in get_categories():
+        for doc_meta in cat.docs:
+            doc = get_doc(cat.id, doc_meta["slug"])
+            if doc:
+                docs.append(doc)
+    return docs

package/templates/docs-portal/fastapi/backend/app/portal/html_renderer.py

@@ -0,0 +1,229 @@
+"""Renders portal pages as self-contained HTML. No external template engine required."""
+
+from __future__ import annotations
+from html import escape as esc
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from app.portal.docs_reader import DocCategory, DocFile
+
+
+def _base(title: str, project: str, categories: list[DocCategory], content: str) -> str:
+    title = esc(title)
+    project = esc(project)
+    nav_items = []
+    for cat in categories:
+        dropdown_links = "".join(
+            f'<a href="/portal/{esc(cat.id)}/{esc(d["slug"])}" class="dropdown-item">{esc(d["title"])}</a>'
+            for d in cat.docs
+        )
+        nav_items.append(f"""
+            <div class="nav-dropdown">
+                <button class="nav-btn" aria-haspopup="true" aria-expanded="false">{esc(cat.icon)} {esc(cat.label)} ▾</button>
+                <div class="dropdown-content" role="menu">{dropdown_links}</div>
+            </div>
+        """)
+
+    nav_html = "".join(nav_items)
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{title} — {project}</title>
+    <style>
+        * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+        body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; color: #1a1a1a; background: #f8f9fa; }}
+
+        /* Header */
+        .header {{ background: #fff; border-bottom: 1px solid #e5e7eb; position: sticky; top: 0; z-index: 40; }}
+        .header-inner {{ max-width: 1200px; margin: 0 auto; padding: 0 24px; display: flex; align-items: center; justify-content: space-between; height: 64px; }}
+        .logo {{ display: flex; align-items: center; gap: 10px; text-decoration: none; color: #1a1a1a; font-weight: 600; font-size: 16px; }}
+        .logo-icon {{ width: 32px; height: 32px; background: #1a1a1a; border-radius: 8px; display: flex; align-items: center; justify-content: center; color: #fff; font-weight: 700; font-size: 14px; }}
+        .back-link {{ font-size: 14px; color: #6b7280; text-decoration: none; }}
+        .back-link:hover {{ color: #374151; }}
+
+        /* Nav */
+        .nav {{ display: flex; align-items: center; gap: 4px; }}
+        .nav a.overview {{ padding: 8px 12px; border-radius: 8px; font-size: 14px; font-weight: 500; color: #4b5563; text-decoration: none; }}
+        .nav a.overview:hover {{ background: #f3f4f6; color: #1a1a1a; }}
+        .nav-dropdown {{ position: relative; }}
+        .nav-btn {{ padding: 8px 12px; border-radius: 8px; font-size: 14px; font-weight: 500; color: #4b5563; background: none; border: none; cursor: pointer; }}
+        .nav-btn:hover {{ background: #f3f4f6; color: #1a1a1a; }}
+        .dropdown-content {{ display: none; position: absolute; top: 100%; left: 0; margin-top: 4px; min-width: 240px; background: #fff; border-radius: 12px; box-shadow: 0 4px 16px rgba(0,0,0,.1); border: 1px solid #e5e7eb; padding: 8px 0; z-index: 50; }}
+        .nav-dropdown:hover .dropdown-content {{ display: block; }}
+        .dropdown-item {{ display: block; padding: 10px 16px; font-size: 14px; color: #374151; text-decoration: none; }}
+        .dropdown-item:hover {{ background: #f3f4f6; color: #1a1a1a; }}
+
+        /* Content */
+        .content {{ max-width: 1200px; margin: 0 auto; padding: 32px 24px; }}
+
+        /* Cards */
+        .card-grid {{ display: grid; grid-template-columns: repeat(auto-fill, minmax(320px, 1fr)); gap: 16px; }}
+        .card {{ background: #fff; border-radius: 12px; border: 1px solid #e5e7eb; padding: 24px; transition: box-shadow .15s; }}
+        .card:hover {{ box-shadow: 0 4px 12px rgba(0,0,0,.08); }}
+        .card-icon {{ font-size: 28px; margin-bottom: 12px; }}
+        .card h2 {{ font-size: 18px; font-weight: 600; margin-bottom: 4px; }}
+        .card p {{ font-size: 14px; color: #6b7280; margin-bottom: 16px; }}
+        .card-link {{ display: block; font-size: 14px; color: #2563eb; text-decoration: none; padding: 2px 0; }}
+        .card-link:hover {{ color: #1d4ed8; }}
+
+        /* Doc article */
+        .article {{ background: #fff; border-radius: 12px; border: 1px solid #e5e7eb; padding: 48px; max-width: 900px; margin: 0 auto; }}
+        .breadcrumb {{ font-size: 14px; color: #6b7280; margin-bottom: 24px; }}
+        .breadcrumb a {{ color: #6b7280; text-decoration: none; }}
+        .breadcrumb a:hover {{ color: #374151; }}
+        .doc-meta {{ font-size: 13px; color: #9ca3af; margin-top: 8px; }}
+
+        /* Rendered markdown */
+        .prose h1 {{ font-size: 28px; font-weight: 700; margin: 32px 0 16px; }}
+        .prose h1:first-child {{ margin-top: 0; }}
+        .prose h2 {{ font-size: 22px; font-weight: 600; margin: 32px 0 12px; padding-bottom: 8px; border-bottom: 1px solid #e5e7eb; }}
+        .prose h3 {{ font-size: 18px; font-weight: 600; margin: 24px 0 8px; }}
+        .prose p {{ color: #374151; line-height: 1.7; margin: 12px 0; }}
+        .prose ul, .prose ol {{ margin: 12px 0; padding-left: 24px; color: #374151; }}
+        .prose li {{ margin: 6px 0; line-height: 1.6; }}
+        .prose a {{ color: #2563eb; text-decoration: underline; }}
+        .prose a:hover {{ color: #1d4ed8; }}
+        .prose code {{ background: #f3f4f6; padding: 2px 6px; border-radius: 4px; font-size: 13px; }}
+        .prose pre {{ background: #1e293b; color: #e2e8f0; padding: 16px; border-radius: 8px; overflow-x: auto; margin: 16px 0; }}
+        .prose pre code {{ background: none; padding: 0; color: inherit; }}
+        .prose blockquote {{ border-left: 4px solid #bfdbfe; background: #eff6ff; padding: 12px 16px; border-radius: 0 8px 8px 0; margin: 16px 0; }}
+        .prose table {{ width: 100%; border-collapse: collapse; margin: 16px 0; border-radius: 8px; overflow: hidden; border: 1px solid #e5e7eb; }}
+        .prose th {{ background: #f9fafb; padding: 12px 16px; text-align: left; font-size: 12px; font-weight: 600; color: #4b5563; text-transform: uppercase; letter-spacing: .05em; }}
+        .prose td {{ padding: 12px 16px; font-size: 14px; color: #374151; border-top: 1px solid #f3f4f6; }}
+
+        /* Recent list */
+        .recent {{ background: #fff; border-radius: 12px; border: 1px solid #e5e7eb; padding: 24px; margin-top: 24px; }}
+        .recent h2 {{ font-size: 18px; font-weight: 600; margin-bottom: 16px; }}
+        .recent-item {{ display: flex; justify-content: space-between; align-items: center; padding: 12px 0; border-top: 1px solid #f3f4f6; }}
+        .recent-item:first-of-type {{ border-top: none; }}
+        .recent-item a {{ font-size: 14px; font-weight: 500; color: #1a1a1a; text-decoration: none; }}
+        .recent-item a:hover {{ color: #2563eb; }}
+        .recent-item .meta {{ font-size: 12px; color: #9ca3af; }}
+
+        /* Empty state */
+        .empty {{ text-align: center; padding: 80px 24px; }}
+        .empty .icon {{ font-size: 48px; margin-bottom: 16px; }}
+        .empty h1 {{ font-size: 24px; font-weight: 700; margin-bottom: 8px; }}
+        .empty p {{ color: #6b7280; max-width: 400px; margin: 0 auto; }}
+
+        @media (max-width: 768px) {{
+            .card-grid {{ grid-template-columns: 1fr; }}
+            .article {{ padding: 24px; }}
+            .nav {{ display: none; }}
+        }}
+    </style>
+</head>
+<body>
+    <header class="header">
+        <div class="header-inner">
+            <div style="display:flex;align-items:center;gap:24px;">
+                <a href="/portal" class="logo">
+                    <div class="logo-icon">{esc(project[0]) if project else "?"}</div>
+                    {project}
+                </a>
+                <nav class="nav">
+                    <a href="/portal" class="overview">Overview</a>
+                    {nav_html}
+                </nav>
+            </div>
+            <a href="/docs" class="back-link">API docs</a>
+        </div>
+    </header>
+    <div class="content">
+        {content}
+    </div>
+</body>
+</html>"""
+
+
+def render_portal_home(categories: list[DocCategory], recent: list[DocFile], project: str) -> str:
+    if not categories:
+        content = """
+            <div class="empty">
+                <div class="icon">📄</div>
+                <h1>No documentation yet</h1>
+                <p>Documentation will appear here once it has been generated. Ask your development team to run the documentation generators.</p>
+            </div>
+        """
+        return _base("Portal", project, categories, content)
+
+    cards = ""
+    for cat in categories:
+        links = "".join(
+            f'<a href="/portal/{esc(cat.id)}/{esc(d["slug"])}" class="card-link">{esc(d["title"])}</a>'
+            for d in cat.docs
+        )
+        cards += f"""
+            <div class="card">
+                <div class="card-icon">{esc(cat.icon)}</div>
+                <h2>{esc(cat.label)}</h2>
+                <p>{esc(cat.description)}</p>
+                {links}
+            </div>
+        """
+
+    recent_items = ""
+    for doc in recent:
+        date_str = doc.last_modified.strftime("%b %d, %Y")
+        recent_items += f"""
+            <div class="recent-item">
+                <div>
+                    <a href="/portal/{esc(doc.category)}/{esc(doc.slug)}">{esc(doc.title)}</a>
+                    <span class="meta" style="margin-left:8px;">{esc(doc.category_label)}</span>
+                </div>
+                <span class="meta">{date_str}</span>
+            </div>
+        """
+
+    content = f"""
+        <h1 style="font-size:28px;font-weight:700;margin-bottom:8px;">Project Documentation</h1>
+        <p style="color:#6b7280;margin-bottom:24px;">Everything you need to know about this project — requirements, architecture, test results, and more.</p>
+        <div class="card-grid">{cards}</div>
+        <div class="recent">
+            <h2>Recently Updated</h2>
+            {recent_items}
+        </div>
+    """
+    return _base("Portal", project, categories, content)
+
+
+def render_category_page(cat: DocCategory, categories: list[DocCategory], project: str) -> str:
+    items = ""
+    for d in cat.docs:
+        items += f"""
+            <a href="/portal/{esc(cat.id)}/{esc(d["slug"])}" class="card" style="text-decoration:none;display:block;">
+                <h2 style="color:#1a1a1a;">{esc(d["title"])}</h2>
+            </a>
+        """
+
+    content = f"""
+        <div class="breadcrumb">
+            <a href="/portal">Portal</a> / <span>{esc(cat.label)}</span>
+        </div>
+        <h1 style="font-size:28px;font-weight:700;margin-bottom:8px;">{esc(cat.icon)} {esc(cat.label)}</h1>
+        <p style="color:#6b7280;margin-bottom:24px;">{esc(cat.description)}</p>
+        <div class="card-grid">{items}</div>
+    """
+    return _base(cat.label, project, categories, content)
+
+
+def render_doc_page(doc: DocFile, categories: list[DocCategory], project: str) -> str:
+    date_str = doc.last_modified.strftime("%B %d, %Y")
+    # doc.html is already rendered markdown — titles and metadata need escaping
+    content = f"""
+        <div class="article">
+            <div class="breadcrumb">
+                <a href="/portal">Portal</a> /
+                <a href="/portal/{esc(doc.category)}">{esc(doc.category_label)}</a> /
+                <span>{esc(doc.title)}</span>
+            </div>
+            <h1 style="font-size:28px;font-weight:700;margin-bottom:4px;">{esc(doc.title)}</h1>
+            <p class="doc-meta">Last updated {date_str}</p>
+            <hr style="margin:24px 0;border:none;border-top:1px solid #e5e7eb;">
+            <div class="prose">{doc.html}</div>
+        </div>
+    """
+    return _base(doc.title, project, categories, content)

package/templates/docs-portal/fastapi/backend/app/portal/router.py.template

@@ -0,0 +1,35 @@
+"""Portal routes — serves project documentation as HTML pages."""
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse
+
+from app.portal.docs_reader import get_categories, get_doc, get_all_docs
+from app.portal.html_renderer import render_portal_home, render_category_page, render_doc_page
+
+router = APIRouter(prefix="/portal", tags=["portal"])
+
+
+@router.get("/", response_class=HTMLResponse)
+async def portal_home(request: Request):
+    categories = get_categories()
+    all_docs = get_all_docs()
+    recent = sorted(all_docs, key=lambda d: d.last_modified, reverse=True)[:5]
+    return render_portal_home(categories, recent, "{{PROJECT_NAME_PASCAL}}")
+
+
+@router.get("/{category}", response_class=HTMLResponse)
+async def category_page(category: str):
+    categories = get_categories()
+    cat = next((c for c in categories if c.id == category), None)
+    if not cat:
+        return HTMLResponse("<h1>Not found</h1>", status_code=404)
+    return render_category_page(cat, categories, "{{PROJECT_NAME_PASCAL}}")
+
+
+@router.get("/{category}/{slug}", response_class=HTMLResponse)
+async def doc_page(category: str, slug: str):
+    doc = get_doc(category, slug)
+    if not doc:
+        return HTMLResponse("<h1>Not found</h1>", status_code=404)
+    categories = get_categories()
+    return render_doc_page(doc, categories, "{{PROJECT_NAME_PASCAL}}")