LICENSE Documentation

1. Project Overview & Quickstart (fullstackhero/LICENSE) Copy Chapter

LICENSE

Open-source repository fullstackhero/LICENSE

Repository Details Copy Section

• Repository: fullstackhero/LICENSE
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (fullstackhero/docs) Copy Chapter

File: README.md Copy Chapter

FullStackHero Docs

Documentation site for the FullStackHero .NET starter kit. Built with Astro 6 and Tailwind 4.

Local development Copy Chapter

cd docs
npm install
npm run dev

The site runs on http://localhost:4321. Edit MDX files under src/content/docs/ and the dev server hot-reloads. Note that pagefind search is built only by npm run build, so the search modal will report "index not available" during dev.

Build Copy Chapter

npm run build      # astro build && pagefind --site dist
npm run preview    # serves dist/ on a local port

Deploy Copy Chapter

Cloudflare Pages, configured by wrangler.toml. Production branch: main. Build command for the Pages dashboard:

npm ci && npm run build

Output directory: dist.

Content authoring Copy Chapter

Add a new doc page by creating an MDX file under src/content/docs/<section>/. Frontmatter shape is defined by src/content.config.ts:

---
title: Page title
sidebar:
  label: Optional override of title in sidebar
  order: 10                    # lower = higher in section
  hidden: false                # exclude from sidebar but still routable
pageType: guide                # guide | reference | concept | recipe
---

The sidebar tree is derived from file structure. Section labels and order live in src/content/docs/_sections.ts.

Design system Copy Chapter

Tokens, prose styles, and code-block themes are forked verbatim from codewithmukesh/blog (see provenance comments in src/styles/*.css). Brand primary is #15803d (green-700); the user-facing brand green #16a34a lives in --primary-soft so it surfaces in accent text, tinted backgrounds, and the gradient mid-stop.

Search Copy Chapter

Pagefind. Index is generated as a post-build step over the dist/ HTML. Only /docs/* pages are indexed (scoped via data-pagefind-body on the docs <article>). Trigger via Ctrl/Cmd+K.

File: docs/specs/2026-05-24-og-image-generator-design.md Copy Chapter

OG Image Generator - Design

Date: 2026-05-24
Status: Approved, ready for implementation plan

Goal Copy Chapter

Generate per-page Open Graph / Twitter share images (1200×675) for the FullStackHero
documentation site, replacing the current fallback to the 512² square logo
(/logo-fullstackhero.png). Adapt the Playwright-based renderer from
codewithmukesh/blog (scripts/og/generate.mjs), but reshape it from the blog's
one-bespoke-HTML-per-page model into a data-driven generator that produces a card
for every one of the ~86 docs pages from frontmatter, plus the marketing landing and 404.

Why the blog's approach can't be copied verbatim Copy Chapter

The blog hand-crafts one HTML template per article. With 86 docs pages that doesn't scale.
This repo, however, already has the SEO plumbing the generator can plug into:

• seo.ogImage per-page frontmatter (src/content.config.ts).
• A site fallback ogImage: '/logo-fullstackhero.png' (src/data/site.ts).
• BaseLayout.astro absolutizes image ?? siteConfig.ogImage into og:image / twitter:image.
• src/pages/docs/[...slug].astro reads seo.ogImage and passes it down.
• MarketingLayout.astro already forwards an image prop to BaseLayout.

The site also shares the blog's exact fonts (Outfit / Figtree / JetBrains Mono) and dark
background (#0d0e11), so the blog's CSS ports over directly - only the accent color changes
from purple to FSH green (--primary: #15803d, --primary-soft: #16a34a).

Decisions (from brainstorming) Copy Chapter

• Hybrid template model: a data-driven default template per page, with an optional bespoke
  per-page HTML override as an escape hatch for hero pages.
• FSH green, no portrait: adapt the blog's v2 layout; right column shows the FSH triangle
  mark instead of a face portrait.
• Auto-derive by slug + override: images are wired by slug convention; seo.ogImage still wins.
• Four template variants (see below).
• pageType drives accent + badge only within the standard doc template (not separate layouts).
• Commit the generated JPEGs under public/og/ so deploys ship them without running
  Playwright in CI (the build just copies public/).

Template variants Copy Chapter

The generator selects a variant automatically:

pageType accent + badge (within the doc variant):

Architecture Copy Chapter

Components Copy Section

1. scripts/og/template.mjs - pure rendering module.

   • Exports renderDocsTemplate({ variant, eyebrow, title, description, badge, accent })
     returning a full HTML document string.
   • Holds the shared CSS (FSH-green port of the blog's _v2-shared.css).
   • Inlines the FSH logo as a base64 data URI so Playwright setContent needs no file paths.
   • Title auto-sizes by length tier; description truncates to ~150 chars.
   • No I/O, no Playwright - independently testable by inspecting returned HTML.

2. scripts/og/templates/landing.html, scripts/og/templates/404.html - bespoke site cards
   (self-contained HTML referencing the shared styles), rendered to public/og/<name>.jpg.

3. scripts/og/templates/docs/<slug>.html - optional per-page override. If a file exists for
   a slug, the generator renders it instead of the data-driven doc template. Directory starts empty.

4. scripts/og/generate.mjs - orchestrator (adapted from the blog).

   • Globs src/content/docs/**/*.mdx, parses frontmatter with gray-matter.
   • Determines the slug and variant per page (see slug mapping).
   • Resolves section label from src/content/docs/_sections.ts for the eyebrow.
   • For each page: if a bespoke override HTML exists, render it; else build HTML via
     renderDocsTemplate and render via page.setContent.
   • Also renders the named site templates (landing, 404).
   • Screenshots at 1200×675, deviceScaleFactor 2, JPEG quality 88 (identical to the blog).
   • Waits for networkidle + document.fonts.ready before screenshotting.

Slug → output mapping (mirrors `[...slug].astro`) Copy Section

The docs slug is entry.id minus .mdx, with /index stripped and root index → empty.
Output path is public/og/docs/<slug>.jpg, with the root using index:

• root index.mdx → public/og/docs/index.jpg (variant home)
• architecture/index.mdx → public/og/docs/architecture.jpg (variant overview)
• architecture/vertical-slice.mdx → public/og/docs/architecture/vertical-slice.jpg (variant doc)

Variant selection:

• normalized id === 'index' → home
• normalized id ends with /index → overview
• otherwise → doc

Eyebrow text: section label from _sections.ts (e.g. "Architecture"); root/sectionless → "FullStackHero".

CLI Copy Section

node scripts/og/generate.mjs                                   # render everything
node scripts/og/generate.mjs docs/architecture/vertical-slice  # one docs page (by slug)
node scripts/og/generate.mjs landing                           # one named site template

npm run og maps to the no-arg form.

Wiring Copy Chapter

• src/pages/docs/[...slug].astro - change const image = seo.ogImage; to
  const image = seo.ogImage ?? /og/docs/${slugForCrumb || 'index'}.jpg;
• src/pages/index.astro - <MarketingLayout image="/og/landing.jpg">
• src/pages/404.astro - add image="/og/404.jpg" to its <MarketingLayout>.

BaseLayout already turns these relative paths into absolute og:image / twitter:image URLs.
seo.ogImage frontmatter continues to override per page.

package.json Copy Chapter

• devDependencies: playwright, gray-matter.
• script: "og": "node scripts/og/generate.mjs".
• Chromium provisioned once via npx playwright install chromium.

Output & version control Copy Chapter

• Generated JPEGs live under public/og/ (public/og/docs/*.jpg, public/og/landing.jpg,
  public/og/404.jpg) and are committed. npm run build copies public/ into dist/.

Verification Copy Chapter

1. Render one page of each variant (home, overview, doc, plus landing/404); inspect inline.
2. Iterate on the templates until the cards look right.
3. Render all pages.
4. npm run check - type + content-schema validation passes.
5. npm run build - confirms images are emitted into dist/og/** and pages reference the right paths.

Out of scope Copy Chapter

• Running Playwright during CI/build (images are committed instead).
• Per-page bespoke overrides beyond the empty templates/docs/ escape hatch.
• OG images for any future non-docs routes not listed above.

File: src/content/docs/ai-development/agents-md.mdx Copy Chapter

title: AGENTS.md & the .agents Folder lastUpdated: 2026-06-11 sidebar: label: AGENTS.md & .agents/ order: 1 pageType: reference Copy Chapter

AGENTS.md - the canonical guide Copy Chapter

AGENTS.md at the repo root is the single source of truth for AI tools. It's deliberately lean: a
repo map, the tech stack, full-stack build/run commands, a short list of "golden rules" that must never be
broken, and an index pointing into .agents/rules/. Conventions are edited there - not in the bridges.

CLAUDE.md (Claude Code) and GEMINI.md (Gemini CLI) are one-line bridges that import it:

# Claude Code
The canonical project guide is **`AGENTS.md`** (tool-neutral). It is imported below; edit conventions there, not here.

@AGENTS.md

So every tool - and every contributor - reads the same guide, and there's exactly one place to update.

The `.agents/` folder Copy Chapter

AGENTS.md                     ← canonical guide (CLAUDE.md / GEMINI.md import it)
.agents/
├── rules/                    ← conventions & footguns (read on demand)
│   ├── architecture.md          module boundaries, registration, middleware order
│   ├── api-conventions.md       endpoints, CQRS, validation, exceptions, permissions
│   ├── database.md              EF Core, migrations, tenant isolation, query filters
│   ├── eventing.md              domain vs integration events, Outbox/Inbox
│   ├── caching.md  jobs.md  resilience.md  storage.md
│   ├── security.md              CORS, security headers, rate limiting, idempotency, quotas
│   ├── realtime.md  logging.md  testing.md  integration-testing.md
│   ├── buildingblocks-protection.md   read before touching src/BuildingBlocks (it's protected)
│   ├── modules/                 one file per module (identity, multitenancy, chat, files,
│   │                            webhooks, auditing, billing, catalog, tickets, notifications)
│   └── frontend/                shared.md · admin.md · dashboard.md (the two React apps)
├── skills/                   ← task recipes (see Skills & Workflows)
│   └── {skill}/SKILL.md
└── workflows/                ← review / orchestration playbooks
    └── {workflow}.md

Rules - conventions, read on demand Copy Chapter

A rule is knowledge the agent reads before working in an area - the conventions and the footguns
that are easy to get wrong. Rules don't restate what the code or tests already enforce; they point at the
enforcement and capture the non-obvious. The root AGENTS.md carries the index, e.g. "before EF or
migration work, read database.md."

A few examples of the kind of footgun these capture: registering a module touches four places (Mediator
assemblies + module array, in both the API and DbMigrator hosts); tenant isolation is default-on via
BaseDbContext; new entity ids use Guid.CreateVersion7(); log messages must be structured (no string
interpolation). Each is one read away when the agent needs it.

Next: the Skills & Workflows that turn these conventions
into repeatable actions.

File: src/content/docs/ai-development/claude-code.mdx Copy Chapter

title: Developing with Claude Code lastUpdated: 2026-05-24 sidebar: label: Developing with Claude Code order: 3 pageType: guide seo: title: 'Developing fullstackhero with Claude Code' keywords: 'Claude Code, .NET, AGENTS.md, AI pair programming, fullstackhero, agent skills, code review workflow' Copy Chapter

Claude Code is Anthropic's agentic CLI. Because
this repo is wired with AGENTS.md and .agents/, Claude works on-convention out of the box - it
scaffolds slices, wires modules, and writes migrations the way the kit expects.

1. Install & open Copy Chapter

npm install @anthropic-ai/claude-code   # see the official docs for native installers
cd dotnet-starter-kit
claude

On startup, Claude Code reads CLAUDE.md, which imports AGENTS.md - so the repo map, golden rules, and
the rules index are in context immediately. The detailed rule files load on demand as Claude works.

2. Build features by describing them Copy Chapter

You don't invoke skills by name - describe the task and the matching skill activates:

Each skill ends by building/testing, so you get working, on-convention code rather than a sketch.

3. Review before you commit Copy Chapter

Two read-only workflows act as guardrails - ask for them by intent:

"Review my changes"          → code-reviewer   (diff vs. conventions, structured report)
"Check architecture"         → architecture-guard (boundaries, BuildingBlocks, arch tests)

If the Roslyn navigator MCP is configured (the dotnet-claude-kit plugin), the reviewer also runs
detect_antipatterns and get_diagnostics for machine-found issues.

4. The build/test loop Copy Chapter

dotnet build src/FSH.Starter.slnx     # 0 warnings - the repo runs TreatWarningsAsErrors
dotnet test src/FSH.Starter.slnx      # unit + architecture + integration

To see it all running, the Aspire AppHost brings up the whole stack - Postgres, Valkey, MinIO, the migrator,
the API, and both React apps - with one command:

dotnet run --project src/Host/FSH.Starter.AppHost

5. Golden rules worth remembering Copy Chapter

Claude follows these from AGENTS.md; knowing them helps you review its work:

• Module boundaries - modules talk only through *.Contracts. Enforced by Architecture.Tests.
• Registering a module touches four places - Mediator assemblies + module array, in both the API and DbMigrator hosts. A missing Mediator marker means handlers silently don't run.
• Tenant isolation is default-on via BaseDbContext; opt out only via IGlobalEntity.
• Every command + paginated query needs a validator; handlers are public sealed, return ValueTask<T>.
• Structured logging only - no string interpolation in log messages.
• Don't modify src/BuildingBlocks without intent - it's shared by every module.

6. Keep the guidance sharp Copy Chapter

The .agents/ set is living documentation. When you establish a new convention or hit a new footgun, add
or update a rule (or a skill), commit it, and the whole team's agents improve. The
AGENTS.md & .agents/ page explains the structure;
Skills & Workflows shows how to extend the set.

File: src/content/docs/ai-development/index.mdx Copy Chapter

title: Overview lastUpdated: 2026-05-24 sidebar: label: Overview order: 0 pageType: concept seo: title: 'AI-Driven Development with fullstackhero' keywords: 'AGENTS.md, .agents folder, Claude Code, AI coding agent, agent rules skills workflows, .NET starter kit AI' Copy Chapter

fullstackhero ships agent-ready. The conventions, footguns, and step-by-step recipes that normally
live in a senior engineer's head are written down in a form AI coding tools read on demand - so an agent
scaffolds a feature, adds a module, or writes a migration the same way you would, without breaking the
architecture.

Two pieces make this work:

• AGENTS.md - the single, tool-neutral guide at the repo root. CLAUDE.md and GEMINI.md are thin bridges that import it, so every tool reads the same source of truth.
• .agents/ - a folder of rules (conventions, read on demand), skills (task recipes), and workflows (review/orchestration playbooks).

// src/Host/FSH.Starter.Api/Program.cs (condensed)
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMediator(o =>
{
    o.ServiceLifetime = ServiceLifetime.Scoped;
    o.Assemblies = [
        typeof(GenerateTokenCommand), typeof(GenerateTokenCommandHandler),   // Identity - Contracts + runtime
        typeof(GetTenantStatusQuery), typeof(GetTenantStatusQueryHandler),   // Multitenancy - Contracts + runtime
        /* …two marker types per module, for all ten modules… */ ];
});

var moduleAssemblies = new Assembly[]
{
    typeof(IdentityModule).Assembly,
    typeof(MultitenancyModule).Assembly,
    /* …all ten module runtime assemblies… */
};

builder.AddHeroPlatform(o => { o.EnableCaching = true; o.EnableJobs = true; /* … */ });
builder.AddModules(moduleAssemblies);

var app = builder.Build();
app.UseHeroMultiTenantDatabases();   // Finbuckle UseMultiTenant() - before the rest of the pipeline
app.UseHeroPlatform(p => { p.MapModules = true; /* … */ });
await app.RunAsync();

// BuildingBlocks/Web/Modules/IModule.cs
public interface IModule
{
    void ConfigureServices(IHostApplicationBuilder builder);
    void MapEndpoints(IEndpointRouteBuilder endpoints);
    void ConfigureMiddleware(IApplicationBuilder app) { }   // optional - default no-op
}

// Modules.Identity/AssemblyInfo.cs
[assembly: FshModule(typeof(FSH.Modules.Identity.IdentityModule), 100)]

// Modules.Identity/IdentityModule.cs (condensed)
public class IdentityModule : IModule
{
    public void ConfigureServices(IHostApplicationBuilder builder)
    {
        PermissionConstants.Register(IdentityPermissions.All);
        builder.Services.AddScoped();
        builder.Services.AddHeroDbContext();
        // ...
    }

    public void MapEndpoints(IEndpointRouteBuilder endpoints)
    {
        var group = endpoints.MapGroup("api/v{version:apiVersion}/identity")
                             .WithTags("Identity")
                             .WithApiVersionSet(apiVersionSet);
        group.MapGenerateTokenEndpoint().AllowAnonymous().RequireRateLimiting("auth");
        group.MapRegisterUserEndpoint();
        // ... the rest of the module's endpoints
    }
}

PermissionConstants.Register(IdentityPermissions.All);
PermissionConstants.Register(CatalogPermissions.All);
PermissionConstants.Register(TicketsPermissions.All);
// ...

1.  UseExceptionHandler            → RFC 9457 ProblemDetails
2.  UseResponseCompression
3.  UseCors                        ← before HTTPS redirect (preflight)
4.  UseHttpsRedirection
5.  Security headers
6.  UseStaticFiles                 (optional)
7.  Hangfire dashboard             (if jobs enabled)
8.  UseRouting
9.  OpenAPI + Scalar
10. UseAuthentication
11. Per-module ConfigureMiddleware ← multi-tenant root override etc.
12. UseRateLimiter
13. Quota enforcement              (if quotas enabled)
14. UseAuthorization
15. Per-module MapEndpoints
16. Health, SSE, SignalR
17. CurrentUserMiddleware          ← last, so authorization already done

// Architecture.Tests/ModuleArchitectureTests.cs (condensed)
[Fact]
public void Modules_Should_Not_Depend_On_Other_Modules()
{
    // for every Modules.*.csproj (excluding *.Contracts), assert no ProjectReference
    // points at another module's runtime project
    isSelfReference.ShouldBeTrue(
        $"Module runtime project '{currentName}' must not reference other module runtime project '{referencedName}'. " +
        "Only contracts or building block projects are allowed.");
}