From 2a21eca3f26f4ea73f0f5fc9bfa12b08ff07f959 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Wed, 22 Jul 2026 23:43:55 +0200
Subject: [PATCH 1/7] feat: enhance ShellDocs with new content and API
 reference primitives, including improved component registration and authoring
 templates

---
 docs/ROADMAP.md | 48 ++++++++++++++++++++++++++++++++++++------------
 1 file changed, 36 insertions(+), 12 deletions(-)

diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index eb17c7d..656851d 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -164,22 +164,46 @@ Ships to `ShellDocs.Components`.
 - `PrevNextNav` — auto-derived from nav graph adjacency, rendered at page bottom
 - `DocsBreadcrumb` — composes ShellUI's `<Breadcrumb>` with docs presets
 
-### `feat/content-primitives`
+### ✅ `feat/content-primitives` — shipped
 Ships to `ShellDocs.Components`.
 
-- `DocsTabs` — multi-tab code containers (`npm` / `yarn` / `pnpm` / `standalone` / `bash` presets)
-- `Callout` — Info / Warning / Tip / Danger box (may reuse ShellUI `<Alert>` with docs styling wrapper)
-- `LinkCard` — card-shaped link with title / description / icon for "Next steps" grids
-- `FileTree` — static folder / file visualization
-- `Steps` — vertical numbered steps for onboarding flows
+- `<CodeGroup>` / `<CodeTab>` — multi-tab code containers with cross-page `SyncKey` sync (`npm` / `pnpm` / `yarn`, etc.)
+- `<Callout>` (Info / Warning / Danger / Tip) with per-variant icon
+- `<Card>` / `<CardGrid>` / `<LinkCard>` — responsive card grid + anchor-shaped link card
+- `<FileTree>` / `<FileTreeItem>` — recursive project-layout diagram with `IsFolder`, `Highlight`, `Comment`
+- `<Steps>` / `<Step>` — CSS-counter numbered ordered list with a badge-on-rail spine
+- Preview-frame overhaul: dropped tabs for a fumadocs-style stacked preview + collapsed code teaser with "View Code" expand — both panels stay mounted, killing the whole class of tab-switch state loss
+- `SlotRenderer` gains recursive nested-markup rendering (`ChildContentRaw` threading, `Dedent` for Markdig 4-space-indent trap) and per-property type coercion for `bool` / `int` / enum attribute values
 
-### `feat/api-reference-primitives`
+### ✅ `feat/api-reference-primitives` — shipped
 Ships to `ShellDocs.Components`.
 
-- `TypeTable` — props table with `<TypeRow Name Type Default Description />` child components
-- `ComponentPreview` — live component render by name + prop dictionary, source-view toggle
-- Uses `<DynamicComponent>` for runtime component rendering
-- Type registry from `ShellDocs.Markdown` reused
+- `<TypeTable>` / `<TypeRow Name Type Default Description Required />` — hand-authored props reference table via `CascadingValue` registration
+- `<ComponentPreview Component="Foo" ...props>` — declarative-prop cousin of `razor:preview`; resolves target by name through `TypeRegistry`, forwards attrs via `CaptureUnmatchedValues` with the same per-type coercion `SlotRenderer` uses, reconstructs source view from the resolved prop dict (self-closing form when no body)
+- `SlotRenderer.Coerce` + `GetParameterProps` bumped to `internal` so `ComponentPreview` can drive the same conversion path
+
+### ✅ `feat/consumer-registration-dx` — shipped
+Ships to `ShellDocs.Components` + `ShellDocs.Templates` + `ShellDocs.CLI` + `ShellDocs.Markdown`.
+
+**Registration (`ShellDocs.Components`)**
+- `ShellDocsOptions.RegisterComponentsFromAssembly<TMarker>()` — assembly-scan overload that walks the marker's assembly for public, concrete, non-generic `ComponentBase` subclasses and registers each. Kills the "hand-type `RegisterComponent<T>()` for every ShellUI component" tax for consumers.
+- `RegisterComponentsFromAssembly(Assembly, Func<Type, bool>?)` — explicit form with a filter predicate for finer control (namespace narrowing, opt-in subsets, etc.)
+- `[ShellDocsIgnore]` attribute — opt-out marker for public components that shouldn't be reachable from markdown authoring (e.g. render-machinery components that live in the same assembly)
+- `RegisterComponent(Type)` runtime overload alongside the existing generic form
+- `RegisterComponent<T>(string tagName)` + `RegisterComponent(Type, string tagName)` — alias overloads that expose a component under a different markdown-facing tag (e.g. `<Btn>` for `ShellUI.Button`); backed by a per-type `ComponentAliases` dictionary that `BuildTypeRegistry` consults before falling back to `type.Name`
+- **Dogfooded on ourselves:** `AddShellDocs` now scans `ShellDocs.Components.Content` via this API instead of the old explicit-list `RegisterComponent<Callout>(); .RegisterComponent<Card>(); …` block, so a new primitive dropped under `Content/` auto-appears without a maintainer edit to `ServiceCollectionExtensions.cs`. `MarkdownContent` and `PreviewFrame` opt out via `[ShellDocsIgnore]`.
+
+**Content scaffolding (`ShellDocs.Templates` + `ShellDocs.CLI`)**
+- `shelldocs add <template> <name> [--dir] [--force]` — CLI command that scaffolds a starter `.md` page from a template into `content/`. Templates:
+  - `component <Name>` → `content/docs/components/<slug>.md` — frontmatter + intro + `razor:preview` block + empty `<TypeTable>` + Notes
+  - `guide <slug>` → `content/docs/guides/<slug>.md` — frontmatter + intro + `<Steps>` skeleton
+  - `page <slug>` → `content/docs/<slug>.md` — blank frontmatter + H1
+- Slugifies PascalCase inputs (`MyBigCard` → `my-big-card.md`) and TitleCases kebab inputs (`getting-started` → "Getting Started"). Refuses to overwrite unless `--force`.
+- `PageTemplates` static class in `ShellDocs.Templates` holds the three template bodies — same access pattern as the existing `StarterPageTemplate`.
+- Replaces the placeholder `new` command stub in `Program.cs`.
+
+**Authoring fix (`ShellDocs.Markdown`)**
+- `SlotExtractor.ReplaceComponentTags` no longer `.Trim()`s the raw child content of inline component tags. The Trim was stripping the first line's indent and defeating `SlotRenderer.Dedent` — Markdig then interpreted the remaining 4-space-indented lines as an indented code block. Symptom was the same "literal `<pre>` around placeholder divs" bug that had already been fixed for `razor:preview` fences; the inline-tag code path was still hitting it.
 
 ### `feat/animation-polish`
 Ships to `ShellDocs.Components`.
@@ -197,7 +221,7 @@ Ships to `ShellDocs.Components`.
 - Version bump, notes, NuGet push
 - Ready for dogfood via shellui.dev
 
-**Milestone:** ShellDocs is feature-complete for a full-featured docs site. Real content authoring can begin.
+**Milestone:** ShellDocs is feature-complete for a full-featured docs site. Real content authoring can begin. Remaining Phase 2 work: `feat/animation-polish` (nice-to-have) and the `0.2.0-alpha` NuGet cut.
 
 ---
 

From af53e4960ecd61b3b6d85c02ae5b2ad37007b323 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Wed, 22 Jul 2026 23:44:27 +0200
Subject: [PATCH 2/7] feat: replace 'new' command with 'add' for scaffolding
 new documentation pages, introducing template options and file handling logic

---
 src/ShellDocs.CLI/Commands/AddCommand.cs | 113 +++++++++++++++++++++++
 src/ShellDocs.CLI/Program.cs             |  23 +++--
 2 files changed, 128 insertions(+), 8 deletions(-)
 create mode 100644 src/ShellDocs.CLI/Commands/AddCommand.cs

diff --git a/src/ShellDocs.CLI/Commands/AddCommand.cs b/src/ShellDocs.CLI/Commands/AddCommand.cs
new file mode 100644
index 0000000..8cbc9c3
--- /dev/null
+++ b/src/ShellDocs.CLI/Commands/AddCommand.cs
@@ -0,0 +1,113 @@
+using System.Text.RegularExpressions;
+using ShellDocs.Templates;
+using Spectre.Console;
+
+namespace ShellDocs.CLI.Commands;
+
+/* `shelldocs add <template> <name>` — scaffolds a starter markdown page from a
+   template into the project's content root. Templates:
+     component — content/docs/components/<slug>.md   (razor:preview + TypeTable skeleton)
+     guide     — content/docs/guides/<slug>.md       (Steps skeleton)
+     page      — content/docs/<slug>.md              (blank frontmatter + title)
+
+   Slugifies component-style names ("MyBigCard" → "my-big-card"), preserves
+   kebab/snake input verbatim, and refuses to overwrite an existing file unless
+   --force is passed. */
+internal static class AddCommand
+{
+    public static int Run(string template, string name, string dir, bool force)
+    {
+        var templateKey = (template ?? "").Trim().ToLowerInvariant();
+        if (string.IsNullOrEmpty(name))
+        {
+            AnsiConsole.MarkupLine("[red]error:[/] name is required.");
+            AnsiConsole.MarkupLine("[dim]usage: shelldocs add <component|guide|page> <name>[/]");
+            return 1;
+        }
+
+        var contentRoot = ResolveContentRoot(dir);
+        if (contentRoot is null)
+        {
+            AnsiConsole.MarkupLine($"[red]error:[/] no [yellow]content/[/] directory found under [yellow]{dir}[/].");
+            AnsiConsole.MarkupLine("[dim]run this from your docs project root, or use --dir to point at it.[/]");
+            return 1;
+        }
+
+        var (subDir, displayName, slug, body) = templateKey switch
+        {
+            "component"       => ("docs/components", DisplayName(name), Slugify(name), PageTemplates.ComponentPage(DisplayName(name))),
+            "guide"           => ("docs/guides",     TitleCase(name),   Slugify(name), PageTemplates.GuidePage(TitleCase(name))),
+            "page"            => ("docs",            TitleCase(name),   Slugify(name), PageTemplates.BlankPage(TitleCase(name))),
+            _ => (null, "", "", "")!
+        };
+
+        if (subDir is null)
+        {
+            AnsiConsole.MarkupLine($"[red]error:[/] unknown template [yellow]{template}[/].");
+            AnsiConsole.MarkupLine("[dim]expected one of: [cyan]component[/], [cyan]guide[/], [cyan]page[/].[/]");
+            return 1;
+        }
+
+        var targetDir = Path.Combine(contentRoot, subDir);
+        Directory.CreateDirectory(targetDir);
+        var targetFile = Path.Combine(targetDir, slug + ".md");
+
+        if (File.Exists(targetFile) && !force)
+        {
+            AnsiConsole.MarkupLine($"[red]error:[/] [yellow]{PrettyPath(targetFile)}[/] already exists. Pass [cyan]--force[/] to overwrite.");
+            return 1;
+        }
+
+        File.WriteAllText(targetFile, body);
+        AnsiConsole.MarkupLine($"[green]created[/] [cyan]{PrettyPath(targetFile)}[/]");
+        AnsiConsole.MarkupLine($"[dim]edit the frontmatter + TODOs, then reload the dev server.[/]");
+        return 0;
+    }
+
+    private static string? ResolveContentRoot(string dir)
+    {
+        var abs = Path.GetFullPath(dir);
+        var candidate = Path.Combine(abs, "content");
+        if (Directory.Exists(candidate)) return candidate;
+        return null;
+    }
+
+    /* "MyBigCard" → "my-big-card"; "getting-started" → "getting-started";
+       "Getting Started" → "getting-started"; drops non-alphanumeric except '-' */
+    private static string Slugify(string raw)
+    {
+        var withDashes = Regex.Replace(raw.Trim(), @"(?<=[a-z0-9])(?=[A-Z])", "-");
+        withDashes = Regex.Replace(withDashes, @"[\s_]+", "-");
+        withDashes = Regex.Replace(withDashes, @"[^A-Za-z0-9\-]", "");
+        withDashes = Regex.Replace(withDashes, @"-{2,}", "-").Trim('-');
+        return withDashes.ToLowerInvariant();
+    }
+
+    /* Component name stays PascalCase for the display (matches how <Button> etc.
+       are referenced in razor:preview). If input already contains spaces, keep
+       the first-letter-uppercase form. */
+    private static string DisplayName(string raw)
+    {
+        var trimmed = raw.Trim();
+        if (trimmed.Contains(' ') || trimmed.Contains('-') || trimmed.Contains('_'))
+            return TitleCase(trimmed);
+        return char.IsUpper(trimmed[0]) ? trimmed : char.ToUpper(trimmed[0]) + trimmed[1..];
+    }
+
+    /* "getting-started" → "Getting Started"; "MyGuide" → "My Guide" */
+    private static string TitleCase(string raw)
+    {
+        var spaced = Regex.Replace(raw.Trim(), @"[-_]+", " ");
+        spaced = Regex.Replace(spaced, @"(?<=[a-z0-9])(?=[A-Z])", " ");
+        var parts = spaced.Split(' ', StringSplitOptions.RemoveEmptyEntries);
+        return string.Join(' ', parts.Select(p => char.ToUpper(p[0]) + p[1..].ToLowerInvariant()));
+    }
+
+    private static string PrettyPath(string abs)
+    {
+        var cwd = Directory.GetCurrentDirectory();
+        return abs.StartsWith(cwd, StringComparison.OrdinalIgnoreCase)
+            ? abs[(cwd.Length + 1)..].Replace('\\', '/')
+            : abs.Replace('\\', '/');
+    }
+}
diff --git a/src/ShellDocs.CLI/Program.cs b/src/ShellDocs.CLI/Program.cs
index 70f568c..6531322 100644
--- a/src/ShellDocs.CLI/Program.cs
+++ b/src/ShellDocs.CLI/Program.cs
@@ -21,7 +21,7 @@ private static int Main(string[] args)
     {
         var root = new RootCommand("ShellDocs — the docs framework for .NET.");
         root.Subcommands.Add(CreateInitCommand());
-        root.Subcommands.Add(CreateNewCommand());
+        root.Subcommands.Add(CreateAddCommand());
         root.Subcommands.Add(CreateDevCommand());
         root.Subcommands.Add(CreateBuildCommand());
         root.Subcommands.Add(CreatePreviewCommand());
@@ -69,15 +69,22 @@ private static Command CreateInitCommand()
         return cmd;
     }
 
-    private static Command CreateNewCommand()
+    private static Command CreateAddCommand()
     {
-        var kind = new Argument<string>("kind") { Description = "Template kind: page, component-page." };
-        var name = new Argument<string>("name") { Description = "File name for the new page." };
-        var cmd = new Command("new", "Scaffold a new doc page from a template.") { kind, name };
-        cmd.SetAction(pr =>
+        var template = new Argument<string>("template") { Description = "Template: component, guide, page." };
+        var name = new Argument<string>("name") { Description = "Name of the new page (PascalCase for component, kebab-case for guide/page)." };
+        var dir = new Option<string>("--dir")
         {
-            AnsiConsole.MarkupLine($"[yellow]shelldocs new {pr.GetValue(kind)} {pr.GetValue(name)}[/] — not yet implemented (feat/cli-init).");
-        });
+            Description = "Project directory (default: current dir).",
+            DefaultValueFactory = _ => Directory.GetCurrentDirectory()
+        };
+        var force = new Option<bool>("--force") { Description = "Overwrite an existing file with the same name." };
+        var cmd = new Command("add", "Scaffold a new doc page from a template into content/.") { template, name, dir, force };
+        cmd.SetAction(pr => AddCommand.Run(
+            pr.GetValue(template) ?? "",
+            pr.GetValue(name) ?? "",
+            pr.GetValue(dir) ?? Directory.GetCurrentDirectory(),
+            pr.GetValue(force)));
         return cmd;
     }
 

From cb3a7b9f76d20c515ac61fa293869d32653a6771 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Wed, 22 Jul 2026 23:45:19 +0200
Subject: [PATCH 3/7] feat: add [ShellDocsIgnore] attribute to MarkdownContent
 and PreviewFrame components, and update TypeTable styling for consistency

---
 src/ShellDocs.Components/Content/MarkdownContent.razor | 1 +
 src/ShellDocs.Components/Content/PreviewFrame.razor    | 1 +
 src/ShellDocs.Components/Content/TypeTable.razor       | 2 +-
 src/ShellDocs.Components/Content/TypeTable.razor.css   | 8 ++------
 4 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/src/ShellDocs.Components/Content/MarkdownContent.razor b/src/ShellDocs.Components/Content/MarkdownContent.razor
index 4386318..8d93ba2 100644
--- a/src/ShellDocs.Components/Content/MarkdownContent.razor
+++ b/src/ShellDocs.Components/Content/MarkdownContent.razor
@@ -1,3 +1,4 @@
+@attribute [ShellDocsIgnore]
 @inject MarkdownRenderer Renderer
 @inject IJSRuntime JS
 
diff --git a/src/ShellDocs.Components/Content/PreviewFrame.razor b/src/ShellDocs.Components/Content/PreviewFrame.razor
index 85b8dfe..5f8d2ae 100644
--- a/src/ShellDocs.Components/Content/PreviewFrame.razor
+++ b/src/ShellDocs.Components/Content/PreviewFrame.razor
@@ -1,4 +1,5 @@
 @using ShellDocs.Markdown
+@attribute [ShellDocsIgnore]
 @inject MarkdownRenderer Renderer
 
 <div class="preview-frame @(_expanded ? "expanded" : "collapsed")">
diff --git a/src/ShellDocs.Components/Content/TypeTable.razor b/src/ShellDocs.Components/Content/TypeTable.razor
index 277b65b..062171c 100644
--- a/src/ShellDocs.Components/Content/TypeTable.razor
+++ b/src/ShellDocs.Components/Content/TypeTable.razor
@@ -26,7 +26,7 @@
                             <code>@row.Name</code>
                             @if (row.Required)
                             {
-                                <span class="type-table-required" title="Required">required</span>
+                                <span class="type-table-required" title="Required">Required</span>
                             }
                         </td>
                         <td class="type-table-type">
diff --git a/src/ShellDocs.Components/Content/TypeTable.razor.css b/src/ShellDocs.Components/Content/TypeTable.razor.css
index 4515acb..72b6acf 100644
--- a/src/ShellDocs.Components/Content/TypeTable.razor.css
+++ b/src/ShellDocs.Components/Content/TypeTable.razor.css
@@ -23,9 +23,7 @@
     padding: 0.65rem 0.9rem;
     color: var(--muted-foreground);
     font-weight: 500;
-    font-size: 0.75rem;
-    letter-spacing: 0.02em;
-    text-transform: uppercase;
+    font-size: 0.78rem;
     white-space: nowrap;
 }
 
@@ -60,10 +58,8 @@
     background: color-mix(in oklch, var(--destructive, oklch(0.577 0.245 27.325)) 12%, transparent);
     color: var(--destructive, oklch(0.577 0.245 27.325));
     border-radius: calc(var(--radius) - 4px);
-    font-size: 0.68rem;
+    font-size: 0.72rem;
     font-weight: 600;
-    text-transform: uppercase;
-    letter-spacing: 0.03em;
     white-space: nowrap;
 }
 

From 83e7f29637d23fa6fe94c94650e9527b2abf3dce Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Thu, 23 Jul 2026 00:03:39 +0200
Subject: [PATCH 4/7] feat: enhance component registration with ShellDocsIgnore
 attribute and assembly scanning for automatic registration of public
 components

---
 .../ServiceCollectionExtensions.cs            | 24 ++---
 .../ShellDocsIgnoreAttribute.cs               | 10 +++
 src/ShellDocs.Components/ShellDocsOptions.cs  | 87 ++++++++++++++++++-
 3 files changed, 103 insertions(+), 18 deletions(-)
 create mode 100644 src/ShellDocs.Components/ShellDocsIgnoreAttribute.cs

diff --git a/src/ShellDocs.Components/ServiceCollectionExtensions.cs b/src/ShellDocs.Components/ServiceCollectionExtensions.cs
index be40484..9e9629f 100644
--- a/src/ShellDocs.Components/ServiceCollectionExtensions.cs
+++ b/src/ShellDocs.Components/ServiceCollectionExtensions.cs
@@ -20,22 +20,14 @@ public static IServiceCollection AddShellDocs(this IServiceCollection services,
         services.AddScoped<SidebarCollapseState>();
         services.AddScoped<CodeGroupSyncState>();
 
-        // Auto-register the shipped content primitives so `razor:preview` blocks
-        // in markdown can reference <Callout>, <Card>, <Steps>, <FileTree> etc.
-        // without the consumer calling RegisterComponent<T>() themselves.
-        options.RegisterComponent<Callout>();
-        options.RegisterComponent<Card>();
-        options.RegisterComponent<CardGrid>();
-        options.RegisterComponent<LinkCard>();
-        options.RegisterComponent<Steps>();
-        options.RegisterComponent<Step>();
-        options.RegisterComponent<FileTree>();
-        options.RegisterComponent<FileTreeItem>();
-        options.RegisterComponent<CodeGroup>();
-        options.RegisterComponent<CodeTab>();
-        options.RegisterComponent<TypeTable>();
-        options.RegisterComponent<TypeRow>();
-        options.RegisterComponent<ComponentPreview>();
+        /* Auto-register the shipped content primitives so `razor:preview` blocks
+           in markdown can reference <Callout>, <Card>, <Steps>, <FileTree> etc.
+           without the consumer calling RegisterComponent<T>() themselves.
+           Dogfoods RegisterComponentsFromAssembly against our own Content
+           namespace — new primitives added under Content/ auto-appear here
+           without a maintainer edit to this file. Internal render machinery
+           (MarkdownContent, PreviewFrame) opts out via [ShellDocsIgnore]. */
+        options.RegisterComponentsFromAssembly<Callout>(t => t.Namespace == "ShellDocs.Components.Content");
 
         services.AddSingleton<TypeRegistry>(_ => options.BuildTypeRegistry());
         services.AddSingleton<MarkdownRenderer>(sp => new MarkdownRenderer(sp.GetRequiredService<TypeRegistry>()));
diff --git a/src/ShellDocs.Components/ShellDocsIgnoreAttribute.cs b/src/ShellDocs.Components/ShellDocsIgnoreAttribute.cs
new file mode 100644
index 0000000..bc6357b
--- /dev/null
+++ b/src/ShellDocs.Components/ShellDocsIgnoreAttribute.cs
@@ -0,0 +1,10 @@
+namespace ShellDocs.Components;
+
+/* Marker attribute — put this on a public ComponentBase-derived type to keep it
+   out of ShellDocsOptions.RegisterComponentsFromAssembly(...) scans. Use for
+   internal-shaped components that happen to be `public` for testing / other
+   assemblies but shouldn't be reachable from markdown authoring. */
+[AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
+public sealed class ShellDocsIgnoreAttribute : Attribute
+{
+}
diff --git a/src/ShellDocs.Components/ShellDocsOptions.cs b/src/ShellDocs.Components/ShellDocsOptions.cs
index f9efc3e..4e6db87 100644
--- a/src/ShellDocs.Components/ShellDocsOptions.cs
+++ b/src/ShellDocs.Components/ShellDocsOptions.cs
@@ -1,3 +1,5 @@
+using System.Reflection;
+using Microsoft.AspNetCore.Components;
 using ShellDocs.Markdown;
 
 namespace ShellDocs.Components;
@@ -13,13 +15,88 @@ public class ShellDocsOptions
 
     public List<NavLink> PrimaryNav { get; } = new();
     public List<Type> RegisteredComponents { get; } = new();
+    /* Per-type tag alias — when a type appears here, BuildTypeRegistry uses this
+       string as the markdown-facing tag name instead of the type's short name.
+       Consumers use this to expose a component under a different name in docs
+       (e.g. RegisterComponent<Button>("Btn")). Last-write-wins if the same type
+       is registered under multiple aliases. */
+    public Dictionary<Type, string> ComponentAliases { get; } = new();
 
-    public ShellDocsOptions RegisterComponent<T>() where T : Microsoft.AspNetCore.Components.ComponentBase
+    public ShellDocsOptions RegisterComponent<T>() where T : ComponentBase
     {
         RegisteredComponents.Add(typeof(T));
         return this;
     }
 
+    public ShellDocsOptions RegisterComponent<T>(string tagName) where T : ComponentBase
+    {
+        if (string.IsNullOrWhiteSpace(tagName))
+            throw new ArgumentException("tagName must be non-empty.", nameof(tagName));
+        RegisteredComponents.Add(typeof(T));
+        ComponentAliases[typeof(T)] = tagName;
+        return this;
+    }
+
+    public ShellDocsOptions RegisterComponent(Type type)
+    {
+        if (!typeof(ComponentBase).IsAssignableFrom(type))
+            throw new ArgumentException($"{type.FullName} must derive from ComponentBase.", nameof(type));
+        RegisteredComponents.Add(type);
+        return this;
+    }
+
+    public ShellDocsOptions RegisterComponent(Type type, string tagName)
+    {
+        if (!typeof(ComponentBase).IsAssignableFrom(type))
+            throw new ArgumentException($"{type.FullName} must derive from ComponentBase.", nameof(type));
+        if (string.IsNullOrWhiteSpace(tagName))
+            throw new ArgumentException("tagName must be non-empty.", nameof(tagName));
+        RegisteredComponents.Add(type);
+        ComponentAliases[type] = tagName;
+        return this;
+    }
+
+    /* Scan the assembly that TMarker lives in for all public, concrete,
+       non-generic ComponentBase-derived types and register each. Skips types
+       tagged with [ShellDocsIgnore]. Duplicate registrations against the same
+       tag name are silently ignored downstream in TypeRegistry. */
+    public ShellDocsOptions RegisterComponentsFromAssembly<TMarker>(Func<Type, bool>? filter = null)
+        => RegisterComponentsFromAssembly(typeof(TMarker).Assembly, filter);
+
+    public ShellDocsOptions RegisterComponentsFromAssembly(Assembly assembly, Func<Type, bool>? filter = null)
+    {
+        if (assembly is null) throw new ArgumentNullException(nameof(assembly));
+        foreach (var type in DiscoverComponentTypes(assembly))
+        {
+            if (filter is not null && !filter(type)) continue;
+            RegisteredComponents.Add(type);
+        }
+        return this;
+    }
+
+    private static IEnumerable<Type> DiscoverComponentTypes(Assembly assembly)
+    {
+        Type[] types;
+        try { types = assembly.GetTypes(); }
+        catch (ReflectionTypeLoadException ex)
+        {
+            /* An assembly with a partially-loadable type surface still yields
+               its resolvable types via the exception's Types property (nulls
+               are the unresolvable ones). Salvage what we can. */
+            types = ex.Types.Where(t => t is not null).ToArray()!;
+        }
+        foreach (var t in types)
+        {
+            if (t is null) continue;
+            if (!t.IsClass || t.IsAbstract) continue;
+            if (!t.IsPublic && !t.IsNestedPublic) continue;
+            if (t.IsGenericTypeDefinition) continue;
+            if (!typeof(ComponentBase).IsAssignableFrom(t)) continue;
+            if (t.IsDefined(typeof(ShellDocsIgnoreAttribute), inherit: false)) continue;
+            yield return t;
+        }
+    }
+
     public ShellDocsOptions AddNavLink(string label, string href)
     {
         PrimaryNav.Add(new NavLink(label, href));
@@ -35,7 +112,13 @@ public ShellDocsOptions AddNavMenu(string label, params NavMenuItem[] items)
     internal TypeRegistry BuildTypeRegistry()
     {
         var registry = new TypeRegistry();
-        foreach (var type in RegisteredComponents) registry.Register(type);
+        foreach (var type in RegisteredComponents)
+        {
+            if (ComponentAliases.TryGetValue(type, out var alias))
+                registry.Register(alias, type);
+            else
+                registry.Register(type);
+        }
         return registry;
     }
 }

From d74a998bd25e2e358f7f12092295bcc77b9cbc42 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Thu, 23 Jul 2026 00:04:13 +0200
Subject: [PATCH 5/7] fix: preserve original indentation in SlotExtractor to
 prevent incorrect formatting in Markdig

---
 src/ShellDocs.Markdown/SlotExtractor.cs | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/ShellDocs.Markdown/SlotExtractor.cs b/src/ShellDocs.Markdown/SlotExtractor.cs
index 255f9e0..a26b58a 100644
--- a/src/ShellDocs.Markdown/SlotExtractor.cs
+++ b/src/ShellDocs.Markdown/SlotExtractor.cs
@@ -117,7 +117,12 @@ private string ReplaceComponentTags(string text, List<Slot> slots, List<string>
                     cursor = open.Index + open.Length;
                     continue;
                 }
-                childRaw = text.Substring(open.Index + open.Length, closeStart - (open.Index + open.Length)).Trim();
+                /* Preserve original indentation — SlotRenderer.Dedent normalizes
+                   the common leading whitespace before feeding to Markdig, and
+                   Trim()-ing here would strip the first line's indent and defeat
+                   that (Markdig would then treat the remaining 4-space-indented
+                   lines as an indented code block). */
+                childRaw = text.Substring(open.Index + open.Length, closeStart - (open.Index + open.Length));
                 endIndex = closeEnd;
             }
 

From 1716673bcbd9aa2c05be4f5db543887805ca5306 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Thu, 23 Jul 2026 00:04:40 +0200
Subject: [PATCH 6/7] feat: add starter page templates for components and
 guides to streamline documentation authoring

---
 src/ShellDocs.Templates/PageTemplates.cs | 76 ++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 src/ShellDocs.Templates/PageTemplates.cs

diff --git a/src/ShellDocs.Templates/PageTemplates.cs b/src/ShellDocs.Templates/PageTemplates.cs
new file mode 100644
index 0000000..607c10f
--- /dev/null
+++ b/src/ShellDocs.Templates/PageTemplates.cs
@@ -0,0 +1,76 @@
+namespace ShellDocs.Templates;
+
+/* Starter markdown emitted by `shelldocs add`.
+   Each method returns a self-contained .md string with frontmatter, a title,
+   and a light section skeleton. TODOs mark spots the author should fill in. */
+public static class PageTemplates
+{
+    public static string ComponentPage(string displayName) => $$"""
+---
+title: {{displayName}}
+description: TODO — short one-line description of {{displayName}}.
+category: Components
+order: 100
+---
+
+# {{displayName}}
+
+`<{{displayName}}>` TODO — one-paragraph intro explaining what this component is for and when to use it.
+
+## Basic
+
+```razor:preview
+<{{displayName}} />
+```
+
+## Props
+
+<TypeTable>
+<TypeRow Name="TODO" Type="string" Default="" Description="TODO — describe this prop." />
+</TypeTable>
+
+## Notes
+
+- TODO
+""";
+
+    public static string GuidePage(string displayName) => $$"""
+---
+title: {{displayName}}
+description: TODO — short one-line description of this guide.
+category: Guides
+order: 100
+---
+
+# {{displayName}}
+
+TODO — one-paragraph intro to what this guide covers and who it's for.
+
+## Steps
+
+<Steps>
+<Step Title="First step">
+TODO — first step body.
+</Step>
+<Step Title="Next step">
+TODO.
+</Step>
+</Steps>
+
+## Next
+
+- TODO
+""";
+
+    public static string BlankPage(string displayName) => $$"""
+---
+title: {{displayName}}
+description: TODO
+order: 100
+---
+
+# {{displayName}}
+
+TODO
+""";
+}

From 0c88bf83e68d46beef1047e41a69ad721697e0ca Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Thu, 23 Jul 2026 00:04:55 +0200
Subject: [PATCH 7/7] feat: add integration tests for AddCommand, Assembly
 scanning, and component alias registration to ensure functionality and
 correctness

---
 tests/ShellDocs.Tests/AddCommandTests.cs     | 122 +++++++++++++++++++
 tests/ShellDocs.Tests/AssemblyScanTests.cs   |  94 ++++++++++++++
 tests/ShellDocs.Tests/ComponentAliasTests.cs |  59 +++++++++
 3 files changed, 275 insertions(+)
 create mode 100644 tests/ShellDocs.Tests/AddCommandTests.cs
 create mode 100644 tests/ShellDocs.Tests/AssemblyScanTests.cs
 create mode 100644 tests/ShellDocs.Tests/ComponentAliasTests.cs

diff --git a/tests/ShellDocs.Tests/AddCommandTests.cs b/tests/ShellDocs.Tests/AddCommandTests.cs
new file mode 100644
index 0000000..a00c9b0
--- /dev/null
+++ b/tests/ShellDocs.Tests/AddCommandTests.cs
@@ -0,0 +1,122 @@
+using System.Reflection;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+/* Integration tests for `shelldocs add`. Uses reflection to reach the internal
+   AddCommand.Run entry point (matches the InitCommand test pattern). */
+public class AddCommandTests : IDisposable
+{
+    private readonly string _sandbox;
+    private readonly MethodInfo _run;
+
+    public AddCommandTests()
+    {
+        _sandbox = Path.Combine(Path.GetTempPath(), "shelldocs-add-tests-" + Guid.NewGuid().ToString("N")[..8]);
+        Directory.CreateDirectory(Path.Combine(_sandbox, "content"));
+
+        var cli = AppDomain.CurrentDomain.GetAssemblies()
+            .FirstOrDefault(a => a.GetName().Name == "shelldocs")
+            ?? Assembly.Load("shelldocs");
+        var type = cli.GetType("ShellDocs.CLI.Commands.AddCommand", throwOnError: true)!;
+        _run = type.GetMethod("Run", BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic)!;
+    }
+
+    public void Dispose()
+    {
+        try { Directory.Delete(_sandbox, recursive: true); } catch { }
+    }
+
+    private int Add(string template, string name, bool force = false, string? dir = null) =>
+        (int)_run.Invoke(null, new object?[] { template, name, dir ?? _sandbox, force })!;
+
+    [Fact]
+    public void Add_Component_WritesToContentDocsComponents_WithSlugFilename()
+    {
+        var exit = Add("component", "MyBigCard");
+
+        Assert.Equal(0, exit);
+        var expected = Path.Combine(_sandbox, "content", "docs", "components", "my-big-card.md");
+        Assert.True(File.Exists(expected));
+        var body = File.ReadAllText(expected);
+        Assert.Contains("title: MyBigCard", body);
+        Assert.Contains("`<MyBigCard>`", body);
+        Assert.Contains("razor:preview", body);
+        Assert.Contains("<TypeTable>", body);
+    }
+
+    [Fact]
+    public void Add_Guide_WritesToContentDocsGuides_WithTitleCaseName()
+    {
+        var exit = Add("guide", "getting-started");
+
+        Assert.Equal(0, exit);
+        var expected = Path.Combine(_sandbox, "content", "docs", "guides", "getting-started.md");
+        Assert.True(File.Exists(expected));
+        var body = File.ReadAllText(expected);
+        Assert.Contains("title: Getting Started", body);
+        Assert.Contains("<Steps>", body);
+    }
+
+    [Fact]
+    public void Add_Page_WritesToContentDocs_WithBlankBody()
+    {
+        var exit = Add("page", "faq");
+
+        Assert.Equal(0, exit);
+        var expected = Path.Combine(_sandbox, "content", "docs", "faq.md");
+        Assert.True(File.Exists(expected));
+        var body = File.ReadAllText(expected);
+        Assert.Contains("title: Faq", body);
+        Assert.DoesNotContain("razor:preview", body);
+    }
+
+    [Fact]
+    public void Add_UnknownTemplate_ReturnsNonZero()
+    {
+        Assert.NotEqual(0, Add("widget", "Foo"));
+    }
+
+    [Fact]
+    public void Add_MissingContentDir_ReturnsNonZero()
+    {
+        var stray = Path.Combine(Path.GetTempPath(), "shelldocs-add-no-content-" + Guid.NewGuid().ToString("N")[..8]);
+        Directory.CreateDirectory(stray);
+        try
+        {
+            Assert.NotEqual(0, Add("component", "Foo", dir: stray));
+        }
+        finally
+        {
+            Directory.Delete(stray, recursive: true);
+        }
+    }
+
+    [Fact]
+    public void Add_ExistingFileWithoutForce_Fails()
+    {
+        Add("component", "Duplicate");
+        Assert.NotEqual(0, Add("component", "Duplicate"));
+    }
+
+    [Fact]
+    public void Add_ExistingFileWithForce_Overwrites()
+    {
+        Add("component", "Duplicate");
+        var target = Path.Combine(_sandbox, "content", "docs", "components", "duplicate.md");
+        File.WriteAllText(target, "custom content");
+
+        var exit = Add("component", "Duplicate", force: true);
+
+        Assert.Equal(0, exit);
+        var body = File.ReadAllText(target);
+        Assert.Contains("`<Duplicate>`", body);
+        Assert.DoesNotContain("custom content", body);
+    }
+
+    [Fact]
+    public void Add_EmptyName_ReturnsNonZero()
+    {
+        Assert.NotEqual(0, Add("component", ""));
+    }
+}
diff --git a/tests/ShellDocs.Tests/AssemblyScanTests.cs b/tests/ShellDocs.Tests/AssemblyScanTests.cs
new file mode 100644
index 0000000..55150d8
--- /dev/null
+++ b/tests/ShellDocs.Tests/AssemblyScanTests.cs
@@ -0,0 +1,94 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.Extensions.DependencyInjection;
+using ShellDocs.Components;
+using ShellDocs.Markdown;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class AssemblyScanTests
+{
+    [Fact]
+    public void RegisterComponentsFromAssembly_GenericMarker_PicksUpConcretePublicComponents()
+    {
+        var options = new ShellDocsOptions();
+        options.RegisterComponentsFromAssembly<TestMarker>();
+
+        Assert.Contains(typeof(ScannableAlpha), options.RegisteredComponents);
+        Assert.Contains(typeof(ScannableBeta), options.RegisteredComponents);
+    }
+
+    [Fact]
+    public void RegisterComponentsFromAssembly_SkipsAbstractTypes()
+    {
+        var options = new ShellDocsOptions();
+        options.RegisterComponentsFromAssembly<TestMarker>();
+
+        Assert.DoesNotContain(typeof(AbstractShouldSkip), options.RegisteredComponents);
+    }
+
+    [Fact]
+    public void RegisterComponentsFromAssembly_SkipsGenericDefinitions()
+    {
+        var options = new ShellDocsOptions();
+        options.RegisterComponentsFromAssembly<TestMarker>();
+
+        Assert.DoesNotContain(options.RegisteredComponents, t => t.Name.StartsWith("GenericShouldSkip"));
+    }
+
+    [Fact]
+    public void RegisterComponentsFromAssembly_SkipsNonComponentBase()
+    {
+        var options = new ShellDocsOptions();
+        options.RegisterComponentsFromAssembly<TestMarker>();
+
+        Assert.DoesNotContain(typeof(NotAComponent), options.RegisteredComponents);
+    }
+
+    [Fact]
+    public void RegisterComponentsFromAssembly_RespectsShellDocsIgnore()
+    {
+        var options = new ShellDocsOptions();
+        options.RegisterComponentsFromAssembly<TestMarker>();
+
+        Assert.DoesNotContain(typeof(IgnoredExplicitly), options.RegisteredComponents);
+    }
+
+    [Fact]
+    public void RegisterComponentsFromAssembly_FilterOverload_AppliedOnTopOfSystemRules()
+    {
+        var options = new ShellDocsOptions();
+        options.RegisterComponentsFromAssembly<TestMarker>(t => t.Name == nameof(ScannableAlpha));
+
+        Assert.Contains(typeof(ScannableAlpha), options.RegisteredComponents);
+        Assert.DoesNotContain(typeof(ScannableBeta), options.RegisteredComponents);
+    }
+
+    [Fact]
+    public void RegisterComponentsFromAssembly_FlowsIntoTypeRegistry()
+    {
+        var services = new ServiceCollection();
+        services.AddShellDocs(o => o.RegisterComponentsFromAssembly<TestMarker>());
+        var sp = services.BuildServiceProvider();
+
+        var registry = sp.GetRequiredService<TypeRegistry>();
+        Assert.Equal(typeof(ScannableAlpha), registry.Resolve(nameof(ScannableAlpha)));
+        Assert.Equal(typeof(ScannableBeta), registry.Resolve(nameof(ScannableBeta)));
+    }
+
+    [Fact]
+    public void RegisterComponent_TypeOverload_RejectsNonComponentBase()
+    {
+        var options = new ShellDocsOptions();
+        Assert.Throws<ArgumentException>(() => options.RegisterComponent(typeof(NotAComponent)));
+    }
+
+    // ---- test doubles used by the scan (all live in this assembly) ----
+    public class TestMarker { }
+    public class ScannableAlpha : ComponentBase { }
+    public class ScannableBeta : ComponentBase { }
+    public abstract class AbstractShouldSkip : ComponentBase { }
+    public class GenericShouldSkip<T> : ComponentBase { }
+    public class NotAComponent { }
+    [ShellDocsIgnore] public class IgnoredExplicitly : ComponentBase { }
+}
diff --git a/tests/ShellDocs.Tests/ComponentAliasTests.cs b/tests/ShellDocs.Tests/ComponentAliasTests.cs
new file mode 100644
index 0000000..8e68766
--- /dev/null
+++ b/tests/ShellDocs.Tests/ComponentAliasTests.cs
@@ -0,0 +1,59 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.Extensions.DependencyInjection;
+using ShellDocs.Components;
+using ShellDocs.Markdown;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class ComponentAliasTests
+{
+    [Fact]
+    public void RegisterComponent_GenericAliasOverload_RegistersUnderTagName()
+    {
+        var services = new ServiceCollection();
+        services.AddShellDocs(o => o.RegisterComponent<AliasWidget>("Widget"));
+        var sp = services.BuildServiceProvider();
+        var registry = sp.GetRequiredService<TypeRegistry>();
+
+        Assert.Equal(typeof(AliasWidget), registry.Resolve("Widget"));
+        // The type's short name should NOT resolve when an alias is in effect.
+        Assert.Null(registry.Resolve(nameof(AliasWidget)));
+    }
+
+    [Fact]
+    public void RegisterComponent_TypeAliasOverload_RegistersUnderTagName()
+    {
+        var services = new ServiceCollection();
+        services.AddShellDocs(o => o.RegisterComponent(typeof(AliasWidget), "W"));
+        var sp = services.BuildServiceProvider();
+        var registry = sp.GetRequiredService<TypeRegistry>();
+
+        Assert.Equal(typeof(AliasWidget), registry.Resolve("W"));
+    }
+
+    [Fact]
+    public void RegisterComponent_AliasOverload_RejectsBlankTagName()
+    {
+        var options = new ShellDocsOptions();
+        Assert.Throws<ArgumentException>(() => options.RegisterComponent<AliasWidget>(""));
+        Assert.Throws<ArgumentException>(() => options.RegisterComponent<AliasWidget>("   "));
+    }
+
+    [Fact]
+    public void RegisterComponent_LastAliasWinsForSameType()
+    {
+        var services = new ServiceCollection();
+        services.AddShellDocs(o =>
+        {
+            o.RegisterComponent<AliasWidget>("First");
+            o.RegisterComponent<AliasWidget>("Second");
+        });
+        var sp = services.BuildServiceProvider();
+        var registry = sp.GetRequiredService<TypeRegistry>();
+
+        Assert.Equal(typeof(AliasWidget), registry.Resolve("Second"));
+    }
+
+    public class AliasWidget : ComponentBase { }
+}