coding-os 0.3.2__py3-none-any.whl

templates/aspnet-core/scaffold/src/backend/Backend.sln

@@ -0,0 +1,27 @@
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Backend", "Backend.csproj", "{B1A2C3D4-0001-4001-8001-000000000001}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Backend.Tests", "tests\Backend.Tests\Backend.Tests.csproj", "{B1A2C3D4-0002-4001-8001-000000000002}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{B1A2C3D4-0001-4001-8001-000000000001}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B1A2C3D4-0001-4001-8001-000000000001}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B1A2C3D4-0001-4001-8001-000000000001}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B1A2C3D4-0001-4001-8001-000000000001}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B1A2C3D4-0002-4001-8001-000000000002}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B1A2C3D4-0002-4001-8001-000000000002}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B1A2C3D4-0002-4001-8001-000000000002}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B1A2C3D4-0002-4001-8001-000000000002}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+EndGlobal

templates/aspnet-core/scaffold/src/backend/Common/ExceptionHandlingMiddleware.cs

@@ -0,0 +1,35 @@
+using System.Net.Mime;
+using Microsoft.AspNetCore.Mvc;
+
+namespace {{PROJECT_NAME}}.Common;
+
+// The ONLY place that shapes an error response (RFC 9457 problem shape).
+// Endpoints and services throw typed exceptions; this middleware maps them.
+public sealed class ExceptionHandlingMiddleware(
+    RequestDelegate next,
+    ILogger<ExceptionHandlingMiddleware> logger)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        try
+        {
+            await next(context);
+        }
+        catch (Exception exception)
+        {
+            // Full detail to the logger only; never a stack trace to the client.
+            logger.LogError(exception, "Unhandled exception shaping a 500 response");
+
+            var problem = new ProblemDetails
+            {
+                Type = "about:blank",
+                Title = "Internal Server Error",
+                Status = StatusCodes.Status500InternalServerError,
+            };
+
+            context.Response.StatusCode = problem.Status.Value;
+            context.Response.ContentType = MediaTypeNames.Application.ProblemJson;
+            await context.Response.WriteAsJsonAsync(problem);
+        }
+    }
+}

templates/aspnet-core/scaffold/src/backend/Features/Health/HealthEndpoints.cs

@@ -0,0 +1,10 @@
+namespace {{PROJECT_NAME}}.Features.Health;
+
+// Thin: maps the route and delegates to the service (the host serializes).
+public static class HealthEndpoints
+{
+    public static void Map(IEndpointRouteBuilder routes)
+    {
+        routes.MapGet("/health", (HealthService health) => health.Status());
+    }
+}

templates/aspnet-core/scaffold/src/backend/Features/Health/HealthService.cs

@@ -0,0 +1,9 @@
+namespace {{PROJECT_NAME}}.Features.Health;
+
+// Transport-free service — no HttpContext, so it is unit-testable in isolation.
+public sealed class HealthService
+{
+    public HealthStatus Status() => new("ok");
+}
+
+public sealed record HealthStatus(string Status);

templates/aspnet-core/scaffold/src/backend/Program.cs

@@ -0,0 +1,22 @@
+using {{PROJECT_NAME}}.Common;
+using {{PROJECT_NAME}}.Features.Health;
+
+// Exposed so integration tests build the app without binding a real port
+// (WebApplicationFactory<Program> needs Program to be reachable).
+var builder = WebApplication.CreateBuilder(args);
+
+// DI registrations — services are resolved by the container, never `new`-ed.
+builder.Services.AddScoped<HealthService>();
+
+var app = builder.Build();
+
+// The middleware runs first so it wraps every downstream handler; it is the
+// ONLY place that shapes an error response.
+app.UseMiddleware<ExceptionHandlingMiddleware>();
+
+HealthEndpoints.Map(app);
+
+app.Run();
+
+// Marker class so WebApplicationFactory<Program> can reference the entry point.
+public partial class Program;

templates/aspnet-core/scaffold/src/backend/tests/Backend.Tests/Backend.Tests.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <RootNamespace>{{PROJECT_NAME}}.Tests</RootNamespace>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageReference Include="xunit" Version="2.9.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../../Backend.csproj" />
+  </ItemGroup>
+
+</Project>

templates/aspnet-core/scaffold/src/backend/tests/Backend.Tests/HealthServiceTests.cs

@@ -0,0 +1,15 @@
+using {{PROJECT_NAME}}.Features.Health;
+using Xunit;
+
+namespace {{PROJECT_NAME}}.Tests;
+
+public sealed class HealthServiceTests
+{
+    [Fact]
+    public void Status_ReportsOk()
+    {
+        var health = new HealthService();
+
+        Assert.Equal("ok", health.Status().Status);
+    }
+}

templates/aspnet-core/scaffold-boundary.yaml

@@ -0,0 +1,24 @@
+# Scaffold boundary for the aspnet-core stack.
+# Schema: docs/governance/scaffold-boundary-contract.md
+
+version: 1
+stack: aspnet-core
+
+roots:
+  - src/backend/
+
+file_patterns:
+  - "src/backend/**/*.cs"
+  - "src/backend/**/*.csproj"
+
+imports_from:
+  - src/shared/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/mobile/
+
+notes:
+  - "Endpoints/controllers thin; services own logic; repositories own data access."
+  - "One global exception-handling middleware is the only error-response shaper."

templates/aspnet-core/skills/aspnet-core/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: aspnet-core
+tier: stack
+domain: [backend]
+description: Use when creating or modifying C# files under src/backend/ in an ASP.NET Core service — Program bootstrap, minimal-API endpoints or controllers, services, middleware, DI registrations, DTOs, and their tests. Triggers on any .cs change under src/backend/. Covers DI/container wiring, thin endpoints, the global exception-handling middleware, fail-closed DTO validation, the options pattern for config, and service testing with WebApplicationFactory. Also known as dotnet.
+globs: "src/backend/**/*.cs"
+depends_on:
+  - clean-code
+  - backend-fundamentals
+  - api-design
+last_reviewed: "2026-06-14"
+---
+
+REQUIRED BACKGROUND: You MUST also follow the core `clean-code` and
+`backend-fundamentals` skills. This skill adds ASP.NET Core-specific patterns
+on top.
+
+# aspnet-core
+
+## Layer contract (matches `structure.tree`)
+
+| Layer | May import | Never |
+|---|---|---|
+| `*Endpoints.cs` / controllers | the feature service, DTOs | repositories, other endpoints |
+| `*Service.cs` | repositories, other services | `HttpContext`, `IHttpContextAccessor`, transport types |
+| `Repositories/` | the `DbContext` / DB client | services, endpoints |
+| `Common/` (middleware/filters) | services (for auth lookups) | repositories |
+
+Services stay transport-free — no `HttpContext` — so they are unit-testable and
+a transport swap (minimal API → controllers → gRPC) is an endpoint-layer-only
+change.
+
+## DI & wiring
+
+- Register every service in `Program.cs` (`AddScoped`/`AddSingleton`/`AddTransient`);
+  resolve by constructor or endpoint-parameter injection — never `new` a service.
+- `Program.cs` owns wiring only, not business logic. One `WebApplication`,
+  middleware pipeline registered once, feature endpoints mapped via
+  `<Feature>Endpoints.Map(app)`.
+- Lifetimes: `Scoped` for per-request (the default for services touching the DB),
+  `Singleton` only for stateless/thread-safe helpers, `Transient` for cheap
+  stateless objects. A captive dependency (Singleton holding a Scoped) is a bug.
+- Keep `Program` reachable to tests (`public partial class Program;`) so
+  `WebApplicationFactory<Program>` can build the app without binding a port.
+
+## Endpoints (thin)
+
+- A handler binds/validates the DTO → calls ONE service method → returns the
+  value (the host serializes). Do not build the response envelope by hand.
+- No try/catch for error shaping in an endpoint — throw a typed exception and let
+  the global middleware shape it.
+- Flow `CancellationToken` from the handler into every downstream call.
+
+## Validation
+
+- Every body/route/query input is a validated DTO (DataAnnotations or
+  FluentValidation); reject fail-closed before the service runs. The service
+  receives a typed, validated value and never reads the raw request.
+
+## Error handling
+
+- ONE global `ExceptionHandlingMiddleware` (`Common/ExceptionHandlingMiddleware.cs`)
+  shapes every error response (RFC 9457 problem shape per
+  `docs/api-contracts/error-format.md`). Unknown exceptions → 500 generic
+  message, full detail to the logger only — never a stack trace to the client.
+- Register it first in the pipeline (`app.UseMiddleware<ExceptionHandlingMiddleware>()`)
+  so it wraps all downstream handlers.
+
+## Configuration
+
+- Bind configuration once at bootstrap via the options pattern (`IOptions<T>`);
+  services receive typed options and never read raw configuration keys deep in a
+  method.
+
+## Testing
+
+- Services: pure unit tests, no host — construct with fakes/mocks and assert.
+- Endpoints/integration: `WebApplicationFactory<Program>` builds the app
+  in-memory; one happy + one error-path per endpoint minimum.
+- Never bind a real port in tests; always build through the factory.

templates/aspnet-core/skills/aspnet-core/references/anatomy.md

@@ -0,0 +1,65 @@
+<!-- domain:ASPNETCORE | layer:reference | ssot:true | updated:2026-06-27 -->
+# ASP.NET Core Anatomy
+
+> P: Canonical file map + entity recipes for the ASP.NET Core (minimal-API, feature-folder) stack.
+> R: Adding any `.cs`/`.csproj` under `src/backend/`, or routing a backend task.
+> S: Reading frontend / mobile code — wrong stack.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: `src/templates/aspnet-core/scaffold-boundary.yaml`.
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| Endpoints | `Features/<Feature>/<Feature>Endpoints.cs` | `<Feature>Endpoints.cs` | its service | Thin — maps routes, delegates to the service |
+| Service | `Features/<Feature>/<Feature>Service.cs` | `<Feature>Service.cs` | repository | Business logic (the only layer that thinks) |
+| DTO | `Features/<Feature>/<Feature>Dtos.cs` | `<Feature>Dtos.cs` | none | Request / response records + validation attrs |
+| Middleware | `Common/ExceptionHandlingMiddleware.cs` | `<Name>Middleware.cs` | none | The ONLY error-response shaper (ProblemDetails) |
+| Bootstrap | `Program.cs` | `Program.cs` | Features | `WebApplication` wiring — no business logic |
+| Test | `tests/<Feature>Tests.cs` | `<Feature>Tests.cs` | source under test | xUnit |
+
+## 3. Entity recipes
+
+### Add a new endpoint
+- **Trigger:** "add `POST /<feature>`", "expose endpoint X".
+- **Files emitted:**
+  1. `Features/<Feature>/<Feature>Endpoints.cs`
+  2. `Features/<Feature>/<Feature>Service.cs`
+  3. `Features/<Feature>/<Feature>Dtos.cs`
+- **Steps:**
+  1. Map the route group in `<Feature>Endpoints.cs`; inject the service.
+  2. Validate the DTO before it reaches the service; return typed results.
+  3. Register the service in `Program.cs` DI (`AddScoped`).
+
+### Add a new model
+- **Trigger:** "persist `<Entity>`".
+- **Files emitted:** `Features/<Feature>/<Entity>.cs` (+ EF config).
+- **Steps:**
+  1. Plain record/class; map via the DbContext, never expose it as a DTO.
+
+### Add a new test
+- **Trigger:** any new endpoint / service.
+- **Files emitted:** `tests/<Feature>Tests.cs`.
+- **Steps:**
+  1. `WebApplicationFactory` for endpoint tests; mock the repo for service tests.
+  2. Cover happy + validation-failure paths.
+
+## 4. Conventions
+
+#### Naming
+- Files / types: `PascalCase` (`OrderService.cs`). Locals: `camelCase`; constants: `PascalCase`.
+
+#### Test colocation
+- Mirrored: `tests/<Feature>Tests.cs` mirrors `Features/<Feature>/`.
+
+#### Dependency rules
+- ✓ endpoint → service → repository.
+- ✗ never `new` a service — resolve via the built-in DI container.
+- ✗ `src/backend/` never imports from `src/frontend/` / `src/mobile/` — share via `src/shared/`.

templates/aspnet-core/stack.yaml

@@ -0,0 +1,68 @@
+version: 1
+id: aspnet-core
+language: csharp
+label: "ASP.NET Core + C#"
+category: backend
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── Backend.sln             # solution (app + test projects); verify targets this
+    ├── Backend.csproj
+    ├── Program.cs              # WebApplication bootstrap (no business logic)
+    ├── Common/                 # cross-cutting: exception middleware, problem shaper
+    │   └── ExceptionHandlingMiddleware.cs
+    ├── Features/               # one folder per domain
+    │   └── <Feature>/
+    │       ├── <Feature>Endpoints.cs   # thin — maps routes, delegates to the service
+    │       └── <Feature>Service.cs     # business logic (the only layer that thinks)
+    └── tests/                  # xUnit project (Backend.Tests) — bootable green test
+        └── Backend.Tests/
+  notes: "endpoints/controllers thin, services own logic; one global exception-handling middleware is the ONLY error-response shaper; DTOs validated before reaching a service; DI via the built-in container, never `new` a service"
+primary_skill: aspnet-core
+skills: [aspnet-core]
+
+substitutions:
+  DOMAIN_ROUTES: "Backend→`docs/playbooks/aspnet-core-service.md`"
+  SKILL_ROUTES: "Backend→`aspnet-core`"
+  ENGINEERING_RULE_ROUTING: "Backend→`docs/engineering/aspnet-core-rules.md`, Error format→`docs/api-contracts/error-format.md`"
+  TOOL_ROUTING_IMPL: "`lint-backend`, `test-backend`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-backend + test-backend"
+  VERIFY_BACKEND: "`cd src/backend && dotnet format Backend.sln --verify-no-changes && dotnet test Backend.sln`"
+  QUICK_ROUTING: |-
+    - ASP.NET Core endpoint / controller task → [ASP.NET Core Service Playbook](./playbooks/aspnet-core-service.md)
+    - Middleware / DI / DTO validation → [ASP.NET Core Service Playbook](./playbooks/aspnet-core-service.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-ASPNET` → `./playbooks/aspnet-core-service.md`
+    - `REF:ASPNET-RULES` → `./engineering/aspnet-core-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-ASPNET", path: "./playbooks/aspnet-core-service.md", desc: "ASP.NET Core service playbook"}
+  - {code: "REF:ASPNET-RULES",    path: "./engineering/aspnet-core-rules.md", desc: "ASP.NET Core engineering rules"}
+
+routing_entries:
+  - "ASP.NET Core endpoint / controller task → [ASP.NET Core Service Playbook](./playbooks/aspnet-core-service.md)"
+
+rules:
+  - {file: rules/backend.md, globs: ["src/backend/**/*.cs"]}
+
+makefile_targets:
+  - {name: lint-backend, cmd: "cd src/backend && dotnet format Backend.sln --verify-no-changes"}
+  - {name: test-backend, cmd: "cd src/backend && dotnet test Backend.sln"}
+
+verify:
+  - {glob: "src/backend/**/*.cs", suites: "lint-backend + test-backend", cmd: "cd src/backend && dotnet format Backend.sln --verify-no-changes && dotnet test Backend.sln"}
+
+dimensions:
+  - {name: "ASP.NET Core endpoint",   read_files: ["docs/playbooks/aspnet-core-service.md", "docs/engineering/aspnet-core-rules.md"]}
+  - {name: "Service / business logic", read_files: ["docs/engineering/aspnet-core-rules.md"]}
+  - {name: "Middleware / DI wiring",  read_files: ["docs/engineering/aspnet-core-rules.md"]}
+  - {name: "DTO validation",          read_files: ["docs/engineering/aspnet-core-rules.md", "docs/api-contracts/error-format.md"]}
+  - {name: "Auth / authorization",    read_files: ["docs/engineering/aspnet-core-rules.md"]}
+
+skill_enforcement:
+  - {globs: ["src/backend/**/*.cs"], primary: aspnet-core, secondary: [clean-code, backend-fundamentals, api-design, auth-patterns, security-web, testing-strategy, observability]}
+  - {globs: ["src/backend/**/*Service.cs", "src/backend/**/Repositories/**/*.cs", "src/backend/**/Data/**/*.cs"], primary: aspnet-core, secondary: [clean-code, db-design, backend-fundamentals]}
+  - {globs: ["src/backend/**/*Authorization*.cs", "src/backend/**/Auth*.cs"], primary: aspnet-core, secondary: [auth-patterns, security-web, clean-code]}

templates/astro/rules/frontend.md

@@ -0,0 +1,20 @@
+---
+globs: ["src/frontend/**/*.{ts,tsx,astro}"]
+alwaysApply: false
+---
+
+# Astro Frontend Rules (auto-loaded on src/frontend/**/*.{ts,tsx,astro})
+
+When editing any Astro, TypeScript, or TSX file under `src/frontend/` in an Astro project, follow these standards:
+
+- **Static-first rendering** — `output: "static"` is the default; a page ships zero JS unless an island opts in.
+- **Minimal hydration** — an island uses the narrowest `client:*` directive that works (`client:visible` over `client:load`); never hydrate what static HTML can render.
+- **Islands are leaves** — interactive framework components are extracted leaf islands, not wrappers around `.astro` content.
+- **Content collections are the SSOT** — every content type has a Zod schema in `src/content/config.ts`; querying frontmatter ad-hoc is a review finding.
+- **One error shaper** — only `src/lib/problem.ts` writes API error bodies; endpoints return typed errors, not hand-built JSON.
+- **Strict TypeScript** — `astro check` is the lint gate; `any` requires a written justification.
+- **Build-time data** — `.astro` frontmatter runs at build (SSG); never assume a request context unless the route is explicitly server-rendered.
+
+Canonical policy: `docs/engineering/astro-rules.md`
+Playbook: `docs/playbooks/astro-app.md`
+Primary skill: `astro`

templates/astro/scaffold/docs/engineering/astro-rules.md

@@ -0,0 +1,40 @@
+<!-- domain:FRONTEND | layer:rules | ssot:true | updated:{{DATE}} -->
+# Astro Engineering Rules
+
+Purpose: Non-negotiable conventions for the {{PROJECT_NAME}} Astro frontend — islands, rendering mode, content collections, endpoints.
+Read when: Editing anything under `src/frontend/`.
+Skip when: Backend/mobile work.
+Read next: [Astro App Playbook](../playbooks/astro-app.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Hard rules
+
+1. **Static-first rendering** — `output: "static"` is the default; a page ships
+   zero client JS unless it explicitly hydrates an island. Switching a route to
+   `hybrid`/`server` is a deliberate, justified change, not a convenience.
+2. **Minimal hydration** — an island uses the narrowest `client:*` directive
+   that works: `client:visible`/`client:idle` over `client:load`; `client:only`
+   only when SSR genuinely cannot run. Over-hydration is a review finding.
+3. **Islands are leaves** — interactive framework components are extracted leaf
+   components; the page/layout shell stays a static `.astro` file. Never wrap a
+   whole page in a `client:*` island.
+4. **Content collections are the content SSOT** — every content type has a Zod
+   schema + a Content Layer `loader` in `src/content.config.ts`; entries are
+   validated at build. Pages read
+   via `getCollection()`/`getEntry()` and consume the typed `data` — reading an
+   undeclared frontmatter key is a build-blocking finding.
+5. **One error shaper** — only `src/lib/problem.ts` writes API error bodies
+   (the canonical `{error:{code,message,request_id}}` envelope from
+   `docs/api-contracts/error-format.md`); endpoints return its result and log
+   full detail server-side, never leaking internals to the client.
+6. **Strict TypeScript** — `astro check` is the lint gate (extends
+   `astro/tsconfigs/strict`); `any` requires a written justification at the site.
+7. **Build-time data** — `.astro` frontmatter runs at build (SSG); never assume
+   request context there. Request-time logic lives in an endpoint or an island.
+
+## Testing bar
+
+Pages/components ≥ build green via `astro check` + `astro build`; endpoints ≥
+happy + error path (the `problem()`-shaped response) covered; content schemas
+exercised by at least one entry so the Zod contract is enforced in CI.

templates/astro/scaffold/docs/playbooks/astro-app.md

@@ -0,0 +1,57 @@
+<!-- domain:FRONTEND | layer:playbook | ssot:true | updated:{{DATE}} -->
+# Astro App Playbook
+
+Purpose: The end-to-end recipe for adding or changing a page, island, API endpoint, or content collection in the {{PROJECT_NAME}} Astro app.
+Read when: Any task that adds a `.astro` page or component, a `pages/api/*` endpoint, or a content collection.
+Skip when: SEO copy / metadata strategy — see the Content & SEO Playbook.
+Read next: [Astro Engineering Rules](../engineering/astro-rules.md), [Content & SEO Playbook](./content-seo.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Add a page (the only sanctioned path)
+
+1. **Pick the route** — a file under `src/frontend/src/pages/` IS the route
+   (`pages/about.astro` → `/about`). Pages render at build time (SSG) and ship
+   zero client JS by default.
+2. **Static shell first** — write the page as a plain `.astro` file; pull data
+   in the frontmatter fence (runs at build time only).
+3. **Island only where needed** — extract any genuinely interactive UI into a
+   framework component and hydrate it with the narrowest `client:*` directive
+   (`client:idle`/`client:visible` over `client:load`). Everything else stays
+   static HTML.
+4. **Verify** — `cd src/frontend && npm run lint && npm run build`.
+
+## Add an API endpoint
+
+1. A file under `pages/api/` exporting `GET`/`POST`/… is a server endpoint.
+2. Success returns a thin JSON `Response`; every error goes through the single
+   `lib/problem.ts` shaper (the canonical `{error:{code,message,request_id}}`
+   envelope, [error-format](../api-contracts/error-format.md)) —
+   never build an error body inline.
+3. An endpoint that must run at request time needs `export const prerender = false`
+   (with an adapter), or `output: "server"` in `astro.config.mjs`; keep static
+   pages static.
+
+## Add a content collection
+
+1. Define the collection's Content Layer `loader` (`glob()`) + Zod schema in
+   `src/content.config.ts` — that schema is the content contract; frontmatter is
+   validated at build time.
+2. Add entries as `.md`/`.mdx` under `src/content/<collection>/`.
+3. Read with `getCollection()`; the returned `data` is typed from the schema —
+   never read a frontmatter key the schema does not declare.
+4. SEO/metadata for those pages → [Content & SEO Playbook](./content-seo.md).
+
+## Global wiring (set once)
+
+`astro.config.mjs` owns `output` mode + integrations; `src/lib/problem.ts` owns
+every error response. Both are configured once so all routes inherit them.
+
+## Anti-patterns
+
+- `client:load` on a component that does not need immediate interactivity —
+  defaults to `client:idle`/`client:visible`.
+- An error body built inside an endpoint — the `problem()` helper owns the shape.
+- Reading a frontmatter key the collection schema does not declare — extend the
+  schema in `config.ts` first.
+- Server-rendering a page that could be static — keep `output: "static"`.

templates/astro/scaffold/docs/playbooks/content-seo.md

@@ -0,0 +1,37 @@
+<!-- domain:FRONTEND | layer:playbook | ssot:true | updated:{{DATE}} -->
+# Content & SEO Playbook
+
+Purpose: The recipe for content collections, metadata, structured data, and technical SEO in the {{PROJECT_NAME}} Astro app.
+Read when: A task edits a content collection, page metadata, sitemap, robots, structured data, or AI-discovery files.
+Skip when: The task is component/island UI behavior — see the Astro App Playbook.
+Read next: [Astro App Playbook](./astro-app.md), [Astro Engineering Rules](../engineering/astro-rules.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Content collections (the sanctioned path)
+
+- Define every collection with `defineCollection` + a Content Layer `loader` (`glob()`) + a zod schema in `src/content.config.ts`; frontmatter that fails the schema is a build error, not a silent default.
+- Query with `getCollection` / `getEntry`; never glob-import markdown by hand.
+- Keep rendered copy in the content entry — components receive typed props, they do not embed page prose.
+
+## Metadata & technical SEO
+
+- Centralize `<title>`, description, canonical, and Open Graph / Twitter tags in one layout or a `<SEO>` component; pages pass typed props, never hand-write `<meta>` ad hoc.
+- Generate `sitemap.xml` via `@astrojs/sitemap` in `astro.config.mjs`; keep `robots.txt` in `public/` and aligned with the deployed canonical host.
+- Emit structured data as JSON-LD in a `<script type="application/ld+json">` built from typed data, not string concatenation.
+
+## AI discovery
+
+- Keep `llms.txt` (in `public/`) concise and link out to canonical human-readable docs rather than duplicating them.
+
+## Verification
+
+- `npm run build` succeeds (schema-validates every content entry).
+- Every indexable page resolves a canonical URL and a unique title + description.
+- `sitemap.xml` and `robots.txt` reference the production host, not a preview URL.
+
+## Stop and escalate if
+
+- product positioning or page copy conflicts with the PRD.
+- a content schema change would break already-published entries (plan a migration).
+- a legal/policy page needs review beyond existing SSOT.

templates/astro/scaffold/src/frontend/astro.config.mjs

@@ -0,0 +1,10 @@
+import { defineConfig } from "astro/config";
+
+// SSG by default — pages render to static HTML with zero client JS.
+// API endpoints (pages/api/*.ts) and any client:* island are the only
+// surfaces that ship runtime code. For a route that needs request-time
+// rendering, add `export const prerender = false` to it (and an adapter),
+// or set `output: "server"` when most routes are dynamic.
+export default defineConfig({
+  output: "static",
+});

templates/astro/scaffold/src/frontend/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{PROJECT_NAME}}-frontend",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "lint": "astro check",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "astro": "^7.0.6"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.9",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  }
+}

templates/astro/scaffold/src/frontend/src/components/Greeting.astro

@@ -0,0 +1,13 @@
+---
+// A plain Astro component — renders to static HTML, ships no client JS.
+// To make it interactive, extract the interactive part into a framework
+// component (React/Svelte/Vue) and hydrate it with a client:* directive;
+// keep the static shell here.
+interface Props {
+  name: string;
+}
+
+const { name } = Astro.props;
+---
+
+<p>Hello, {name}.</p>

templates/astro/scaffold/src/frontend/src/content/posts/hello.md

@@ -0,0 +1,10 @@
+---
+title: "Hello from {{PROJECT_NAME}}"
+description: "Sample content collection entry — frontmatter is validated against the Zod schema in content/config.ts at build time."
+publishedAt: {{DATE}}
+draft: false
+---
+
+Replace this with real content. Every field above is type-checked against the
+`posts` collection schema, so a page that renders this entry reads validated,
+typed data — never a guessed frontmatter key.

templates/astro/scaffold/src/frontend/src/content.config.ts

@@ -0,0 +1,19 @@
+import { defineCollection } from "astro:content";
+import { glob } from "astro/loaders";
+import { z } from "astro/zod";
+
+// Content collections are the typed content SSOT. The Content Layer glob()
+// loader reads entries from disk; the Zod schema is the contract — every
+// entry's frontmatter is validated at build time, so a page reading
+// collection data never guesses a field name.
+const posts = defineCollection({
+  loader: glob({ base: "./src/content/posts", pattern: "**/*.md" }),
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    publishedAt: z.coerce.date(),
+    draft: z.boolean().default(false),
+  }),
+});
+
+export const collections = { posts };