feat(armory): add Armory plugin with item gallery, sidebar link, and dashboard block (Sprint B-2)

Add the Armory & Inventory plugin as a view-layer plugin following the NPC
gallery pattern. Items are entities whose entity type has preset_category
"item" — set when created from a system manifest preset.

Key changes:
- Migration 000009: add preset_category column to entity_types table
- EntityType model: add PresetCategory field, plumb through repo/service/input
- Extensions applier: pass category through EntityTypeCreateInput adapter
- New armory plugin: model, repository, service, handler, routes, templ files
- Register "armory" addon in builtinAddons
- Add Armory sidebar link in app.templ Zone 2 (after NPCs)
- Register armory_preview dashboard block in block registry
- Wire armory routes and adapter in routes.go

https://claude.ai/code/session_01WJEjfBqjZaGatHiXXXDupo

Author: claude

db/migrations/000009_entity_type_preset_category.down.sql

@@ -0,0 +1,2 @@
+DROP INDEX idx_entity_types_preset_category ON entity_types;
+ALTER TABLE entity_types DROP COLUMN preset_category;

db/migrations/000009_entity_type_preset_category.up.sql

@@ -0,0 +1,9 @@
+-- Add preset_category column to entity_types.
+-- This tracks which system preset category an entity type was created from
+-- (e.g., "character", "item", "creature"). Used by the Armory plugin to
+-- identify item-type entity types across different game systems.
+ALTER TABLE entity_types
+    ADD COLUMN preset_category VARCHAR(50) DEFAULT NULL AFTER color;
+
+-- Add index for efficient filtering by preset category.
+CREATE INDEX idx_entity_types_preset_category ON entity_types (campaign_id, preset_category);

internal/app/routes.go

@@ -33,6 +33,7 @@ import (
 	"github.com/keyxmakerx/chronicle/internal/templates/layouts"
 	"github.com/keyxmakerx/chronicle/internal/templates/pages"
 	ws "github.com/keyxmakerx/chronicle/internal/websocket"
+	"github.com/keyxmakerx/chronicle/internal/plugins/armory"
 	"github.com/keyxmakerx/chronicle/internal/plugins/npcs"
 	"github.com/keyxmakerx/chronicle/internal/widgets/notes"
 	"github.com/keyxmakerx/chronicle/internal/widgets/posts"
@@ -692,6 +693,44 @@ func (a *npcVisibilityTogglerAdapter) TogglePrivate(ctx context.Context, entityI
 	return a.svc.TogglePrivate(ctx, entityID)
 }
 
+// armoryItemTypeFinderAdapter wraps entities.EntityService to implement the
+// armory.ItemTypeFinder interface. Resolves item-category entity types using
+// the preset_category column.
+type armoryItemTypeFinderAdapter struct {
+	svc entities.EntityService
+}
+
+// FindItemTypeIDs returns the IDs of entity types with preset_category "item".
+func (a *armoryItemTypeFinderAdapter) FindItemTypeIDs(ctx context.Context, campaignID string) ([]int, error) {
+	types, err := a.svc.GetEntityTypesByPresetCategory(ctx, campaignID, "item")
+	if err != nil {
+		return nil, err
+	}
+	ids := make([]int, len(types))
+	for i, t := range types {
+		ids[i] = t.ID
+	}
+	return ids, nil
+}
+
+// FindItemTypes returns item-category entity types for the Armory filter dropdown.
+func (a *armoryItemTypeFinderAdapter) FindItemTypes(ctx context.Context, campaignID string) ([]armory.ItemTypeInfo, error) {
+	types, err := a.svc.GetEntityTypesByPresetCategory(ctx, campaignID, "item")
+	if err != nil {
+		return nil, err
+	}
+	infos := make([]armory.ItemTypeInfo, len(types))
+	for i, t := range types {
+		infos[i] = armory.ItemTypeInfo{
+			ID:    t.ID,
+			Name:  t.Name,
+			Icon:  t.Icon,
+			Color: t.Color,
+		}
+	}
+	return infos, nil
+}
+
 // RegisterRoutes sets up all application routes. It registers public routes
 // directly and delegates to each plugin's route registration function.
 //
@@ -1038,6 +1077,12 @@ func (a *App) RegisterRoutes() {
 	npcHandler.SetVisibilityToggler(&npcVisibilityTogglerAdapter{svc: entityService})
 	npcs.RegisterRoutes(e, npcHandler, campaignService, authService, addonService)
 
+	// Armory plugin: gallery/hub view for item-category entities.
+	armoryRepo := armory.NewArmoryRepository(a.DB)
+	armorySvc := armory.NewArmoryService(armoryRepo, &armoryItemTypeFinderAdapter{svc: entityService})
+	armoryHandler := armory.NewHandler(armorySvc)
+	armory.RegisterRoutes(e, armoryHandler, campaignService, authService, addonService)
+
 	// Notes widget: personal floating note-taking panel (Google Keep-style).
 	noteRepo := notes.NewNoteRepository(a.DB)
 	attRepo := notes.NewAttachmentRepository(a.DB)
@@ -1117,6 +1162,19 @@ func (a *App) RegisterRoutes() {
 		return npcs.BlockNPCGallery(bctx.CC, cards, limit)
 	})
 
+	// Armory preview block — embeds a compact item grid on entity pages/dashboards.
+	blockRegistry.Register(entities.BlockMeta{
+		Type: "armory_preview", Label: "Armory Preview", Icon: "fa-shield-halved",
+		Description: "Grid of campaign items", Addon: "armory",
+	}, func(bctx entities.BlockRenderContext) templ.Component {
+		limit := entities.BlockConfigLimit(bctx.Block.Config, "limit", 8)
+		cards, err := armoryHandler.GalleryBlock(context.Background(), bctx.CC.Campaign.ID, int(bctx.CC.MemberRole), "", limit)
+		if err != nil {
+			return templ.NopComponent
+		}
+		return armory.BlockArmoryPreview(bctx.CC, cards, limit)
+	})
+
 	// Set the registry on the entity service (validation) and as the global (rendering).
 	// The addon checker lets Render() skip blocks whose addon is disabled.
 	blockRegistry.SetAddonChecker(addonService)
@@ -1159,12 +1217,13 @@ func (a *App) RegisterRoutes() {
 	extApplier := extensions.NewContentApplier(
 		a.Config.ExtensionsPath,
 		extRepo,
-		extensions.NewEntityTypeAdapter(func(ctx context.Context, campaignID string, name, namePlural, icon, color string) (int, string, error) {
+		extensions.NewEntityTypeAdapter(func(ctx context.Context, campaignID string, name, namePlural, icon, color, presetCategory string) (int, string, error) {
 			et, err := entityService.CreateEntityType(ctx, campaignID, entities.CreateEntityTypeInput{
-				Name:       name,
-				NamePlural: namePlural,
-				Icon:       icon,
-				Color:      color,
+				Name:           name,
+				NamePlural:     namePlural,
+				Icon:           icon,
+				Color:          color,
+				PresetCategory: presetCategory,
 			})
 			if err != nil {
 				return 0, "", err

internal/extensions/adapters.go

@@ -8,20 +8,20 @@ import "context"
 // entityTypeAdapter wraps any service with a CreateEntityType method
 // matching the entities.EntityService interface.
 type entityTypeAdapter struct {
-	create func(ctx context.Context, campaignID string, name, namePlural, icon, color string) (id int, slug string, err error)
+	create func(ctx context.Context, campaignID string, name, namePlural, icon, color, presetCategory string) (id int, slug string, err error)
 }
 
 // NewEntityTypeAdapter creates an adapter from a creation function.
 // The caller extracts the function from the concrete entity service.
 func NewEntityTypeAdapter(
-	create func(ctx context.Context, campaignID string, name, namePlural, icon, color string) (int, string, error),
+	create func(ctx context.Context, campaignID string, name, namePlural, icon, color, presetCategory string) (int, string, error),
 ) EntityTypeCreator {
 	return &entityTypeAdapter{create: create}
 }
 
 // CreateEntityType implements EntityTypeCreator.
 func (a *entityTypeAdapter) CreateEntityType(ctx context.Context, campaignID string, input EntityTypeCreateInput) (EntityTypeResult, error) {
-	id, slug, err := a.create(ctx, campaignID, input.Name, input.NamePlural, input.Icon, input.Color)
+	id, slug, err := a.create(ctx, campaignID, input.Name, input.NamePlural, input.Icon, input.Color, input.PresetCategory)
 	if err != nil {
 		return EntityTypeResult{}, err
 	}

internal/extensions/applier.go

@@ -31,10 +31,11 @@ type EntityTypeCreator interface {
 // EntityTypeCreateInput mirrors entities.CreateEntityTypeInput to avoid
 // importing the entities package directly.
 type EntityTypeCreateInput struct {
-	Name       string
-	NamePlural string
-	Icon       string
-	Color      string
+	Name           string
+	NamePlural     string
+	Icon           string
+	Color          string
+	PresetCategory string // Optional preset category (e.g., "character", "item").
 }
 
 // EntityTypeResult is the minimal result needed from entity type creation.
@@ -175,10 +176,11 @@ func (a *contentApplier) applyEntityTypeTemplates(
 ) error {
 	for _, t := range templates {
 		input := EntityTypeCreateInput{
-			Name:       t.Name,
-			NamePlural: t.NamePlural,
-			Icon:       t.Icon,
-			Color:      t.Color,
+			Name:           t.Name,
+			NamePlural:     t.NamePlural,
+			Icon:           t.Icon,
+			Color:          t.Color,
+			PresetCategory: t.Category,
 		}
 
 		result, err := a.entityTypes.CreateEntityType(ctx, campaignID, input)

internal/extensions/manifest.go

@@ -72,6 +72,7 @@ type EntityTypeTemplate struct {
 	NamePlural string          `json:"name_plural"`
 	Icon       string          `json:"icon"`
 	Color      string          `json:"color"`
+	Category   string          `json:"category,omitempty"` // Preset category (e.g., "character", "item", "creature").
 	Fields     []TemplateField `json:"fields,omitempty"`
 }
 

internal/plugins/addons/service.go

@@ -149,6 +149,7 @@ var builtinAddons = []addonDef{
 	{Slug: "timeline", Name: "Timeline", Description: "Interactive visual timelines with zoom levels, entity grouping, and calendar integration.", Version: "0.1.0", Category: CategoryPlugin, Status: StatusActive, Icon: "fa-timeline", Author: "Chronicle"},
 	{Slug: "sessions", Name: "Sessions", Description: "Track game sessions with scheduling, linked entities, and RSVP.", Version: "0.1.0", Category: CategoryPlugin, Status: StatusActive, Icon: "fa-calendar-check", Author: "Chronicle"},
 	{Slug: "npcs", Name: "NPC Gallery", Description: "Browse and reveal character entities as NPCs for your players.", Version: "1.0.0", Category: CategoryPlugin, Status: StatusActive, Icon: "fa-users", Author: "Chronicle"},
+	{Slug: "armory", Name: "Armory & Inventory", Description: "Item catalog, character inventories, and shop management. System-dependent item types with Foundry sync.", Version: "0.1.0", Category: CategoryPlugin, Status: StatusActive, Icon: "fa-shield-halved", Author: "Chronicle"},
 
 	// Integrations.
 	{Slug: "sync-api", Name: "Sync API", Description: "Secure REST API for external tool integration (Foundry VTT, Roll20, etc.)", Version: "0.1.0", Category: CategoryIntegration, Status: StatusActive, Icon: "fa-arrows-rotate", Author: "Chronicle"},

internal/plugins/armory/.ai.md

@@ -0,0 +1,27 @@
+# Armory Plugin
+
+## Purpose
+View-layer plugin providing an item gallery/hub for campaign item entities.
+Follows the same pattern as the NPC gallery plugin. Items are entities whose
+entity type has `preset_category = 'item'` (set when created from a system
+manifest preset).
+
+## Architecture
+- **No own tables** — queries `entities` and `entity_types` via the existing
+  entities infrastructure. Uses the `preset_category` column on `entity_types`
+  to identify item types.
+- **Adapter pattern** — `ItemTypeFinder` interface injected from routes.go
+  to resolve item type IDs without circular imports.
+- **Addon-gated** — requires the "armory" addon to be enabled.
+
+## Key Types
+- `ItemCard` — view model for gallery grid cards
+- `ArmoryService` — business logic (list, count, type resolution)
+- `ArmoryRepository` — SQL queries against entities + entity_types
+
+## Routes
+- `GET /campaigns/:id/armory` — gallery page (Player+)
+- `GET /campaigns/:id/armory/count` — JSON count for sidebar badge
+
+## Block
+- `armory_preview` — compact item grid for entity page layouts

internal/plugins/armory/block.templ

@@ -0,0 +1,57 @@
+// block.templ renders the armory_preview layout block — a compact item card
+// grid that can be placed on entity pages and category dashboards.
+package armory
+
+import (
+	"fmt"
+	"github.com/keyxmakerx/chronicle/internal/plugins/campaigns"
+	"github.com/keyxmakerx/chronicle/internal/templates/layouts"
+)
+
+// BlockArmoryPreview renders a compact Armory preview block for entity page layouts.
+// Shows up to `limit` items with images/icons and names.
+templ BlockArmoryPreview(cc *campaigns.CampaignContext, cards []ItemCard, limit int) {
+	<div class="armory-preview-block">
+		<div class="flex items-center justify-between mb-3">
+			<h3 class="text-sm font-semibold text-fg">
+				<i class="fa-solid fa-shield-halved text-fg-muted mr-1.5 text-xs"></i>Armory
+			</h3>
+			<a
+				href={ templ.SafeURL(fmt.Sprintf("/campaigns/%s/armory", cc.Campaign.ID)) }
+				class="text-xs text-accent hover:underline"
+			>
+				View all
+			</a>
+		</div>
+
+		if len(cards) == 0 {
+			<p class="text-xs text-fg-muted text-center py-4">No items in the armory yet.</p>
+		} else {
+			<div class="grid grid-cols-3 sm:grid-cols-4 gap-2">
+				for _, card := range cards {
+					<a
+						href={ templ.SafeURL(fmt.Sprintf("/campaigns/%s/entities/%s", cc.Campaign.ID, card.ID)) }
+						class="group"
+					>
+						<div class="aspect-square rounded-lg overflow-hidden bg-surface-alt mb-1">
+							if card.ImagePath != nil && *card.ImagePath != "" {
+								<img
+									src={ layouts.MediaURL(ctx, *card.ImagePath) }
+									alt={ card.Name }
+									class="w-full h-full object-cover group-hover:scale-105 transition-transform duration-300"
+								/>
+							} else {
+								<div class="w-full h-full flex items-center justify-center">
+									<i class={ "fa-solid " + card.TypeIcon + " text-lg text-fg-muted opacity-30" }></i>
+								</div>
+							}
+						</div>
+						<p class="text-[11px] text-fg truncate text-center group-hover:text-accent transition-colors">
+							{ card.Name }
+						</p>
+					</a>
+				}
+			</div>
+		}
+	</div>
+}