first push

.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm install *)",
+      "Bash(npm --version)",
+      "Bash(npx tsc *)",
+      "Bash(npx vite *)",
+      "Bash(timeout 8 npx tsx src/server/app.ts)",
+      "Bash(node -e \"import\\('occt-import-js'\\).then\\(m => { console.log\\('occt-import-js loaded OK, keys:', Object.keys\\(m\\)\\) }\\).catch\\(e => console.error\\('FAIL:', e.message\\)\\)\")",
+      "Bash(timeout 8 npx tsx --env-file=.env src/server/app.ts)"
+    ]
+  }
+}

.env.example

@@ -0,0 +1,20 @@
+# Copy this file to .env and fill in your values
+# These are used by docker-compose
+
+# Server
+PORT=3000
+BASE_URL=http://your-unraid-ip:3000
+
+# Admin credentials (set before first launch)
+ADMIN_USER=admin
+ADMIN_PASS=changeme
+
+# Session security — generate a random string, e.g.: openssl rand -hex 32
+SESSION_SECRET=change-this-secret-in-production
+
+# File upload limit in megabytes
+MAX_FILE_MB=500
+
+# Bootstrap branding (overridable later in Admin > Settings)
+BRAND_NAME=StepView
+BRAND_ACCENT=#3b82f6

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+public/
+data/
+uploads/
+.env
+*.db
+*.db-wal
+*.db-shm

AGENTS.md

@@ -0,0 +1,68 @@
+# Agent Operating Guide
+
+Use this file as the first entrypoint for work in this repository.
+
+If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) exists and contains filled-in defaults, read it immediately after this file and treat it as the source of preloaded project preferences unless the destination repository provides stronger instructions.
+
+## Default Behavior
+
+- Inspect the repository before making assumptions.
+- Prefer implementing and verifying work over giving abstract advice unless the user explicitly asks for planning only.
+- Read only the skill files needed for the current task.
+- Reuse existing project patterns, naming, architecture, and conventions.
+- Test or validate changes when feasible, then summarize outcomes and any remaining risks.
+- Update or create documentation when the change affects usage, onboarding, behavior, or developer workflow.
+- If repository-specific instructions conflict with this suite, follow the repository-specific instructions.
+
+## How To Load Skills
+
+1. Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in for this deployment.
+2. Read [SKILLS.md](./SKILLS.md).
+3. Identify the task category and open the matching hub file.
+4. Open only the specialized skill files relevant to the request.
+5. Combine skills when the task spans multiple areas.
+6. Avoid loading unrelated skills just because they exist.
+
+## Context Economy Rules
+
+- Default to reading one hub and two to four specialized skills for a normal task.
+- Add more skills only when they materially change the approach, output, or quality bar.
+- Prefer depth in the relevant skills over shallow loading across many categories.
+- If two skills overlap heavily, choose the one that best matches the main risk or deliverable.
+- Re-open the index when the task shifts, but do not reload the entire library reflexively.
+- Treat the deployment profile as the early context layer and avoid re-reading it unless the task changes the relevant preference area.
+
+## Instruction Precedence
+
+Apply guidance in this order:
+
+1. Destination repository instructions
+2. [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md)
+3. Generic routing and skill guidance from this suite
+
+## Routing Table
+
+| Task type | Start here |
+| --- | --- |
+| Feature work, refactors, reviews, tests, backend, frontend | [hubs/software-development.md](./hubs/software-development.md) |
+| Failing tests, bugs, incident-style analysis, root-cause work | [hubs/debugging.md](./hubs/debugging.md) |
+| Technical docs, onboarding, release notes, change communication | [hubs/documentation.md](./hubs/documentation.md) |
+| UX evaluation, UI polish, interaction quality, content design | [hubs/ui-ux.md](./hubs/ui-ux.md) |
+| Product copy, launch messaging, marketing content | [hubs/marketing.md](./hubs/marketing.md) |
+| Ideation, option generation, structured brainstorming | [hubs/brainstorming.md](./hubs/brainstorming.md) |
+
+## Combination Rules
+
+- For new features, combine implementation + test strategy + relevant docs.
+- For UI work, combine frontend implementation + UX review + product copy when text matters.
+- For broken behavior, combine bug triage + debugging workflow + change summary when a fix lands.
+- For launch or release tasks, combine technical docs or release notes with messaging or marketing skills as needed.
+- For high-risk changes, add security review, observability, or performance optimization as appropriate.
+- For long-lived system changes, add architecture and system design, dependency lifecycle, or database migration planning when relevant.
+
+## Output Expectations
+
+- Deliver concrete work products, not just observations.
+- State key assumptions when the repository does not answer them.
+- Call out blockers, tradeoffs, risks, and unverified areas clearly.
+- Keep explanations concise and action-oriented.

DEPLOYMENT-PROFILE.md

@@ -0,0 +1,99 @@
+# Deployment Profile
+
+Use this file to stage prefilled defaults before deploying the suite into other repositories.
+
+This file is the canonical source of preloaded build, tool, environment, workflow, and quality preferences for the deployed bundle. Keep it concise enough to be read early in a session.
+
+## Precedence
+
+1. Destination repository instructions
+2. This deployment profile
+3. Generic `AGENTS.md`, hubs, and skill files
+
+## How To Maintain This File
+
+- Fill out [PROJECT-PROFILE-WORKBOOK.md](./PROJECT-PROFILE-WORKBOOK.md) first.
+- Rewrite the answers here as agent-facing defaults, not as questions.
+- Prefer short, durable defaults over long policy prose.
+- Update this file when your preferred build, tool, or workflow defaults change materially.
+
+## Global Defaults
+
+- Optimize first for full-stack web application repositories.
+- Assume Windows and PowerShell for local development, but keep Docker and Linux deployment realities in mind.
+- Prefer compatibility-first tooling and standard stack defaults when multiple valid tools exist.
+- Favor Node and TypeScript for application work, while using Python when it is the best fit for tooling or automation.
+- Run the most relevant local tests for the changed area by default, and broaden verification for risky changes.
+- Ask clarifying questions before meaningful changes when product intent or risk is unclear.
+- Update documentation for meaningful changes, especially README content, Unraid install docs, roadmaps, and shipped or release-oriented summaries.
+- Hold user-facing work to a high polish bar by default.
+- Provide concise change summaries after meaningful work and call out rollout or migration impact when relevant.
+- Optimize hardest against regressions and broken behavior.
+
+## Software Development Defaults
+
+- Favor modular boundaries and cleaner separation early rather than waiting for severe pain.
+- Operate as a full-stack agent by default and work comfortably across frontend and backend.
+- Prefer mainstream modern patterns for the stack when multiple valid options exist.
+- Assume relational databases first unless the repository clearly indicates otherwise.
+- Be careful with schema and migration work, but do not overengineer small changes.
+- Prefer small, safe, frequent dependency upgrades with focused validation.
+- Treat performance as important early, especially on critical paths.
+- Apply a basic secure-defaults baseline: validate input, handle secrets safely, and respect auth boundaries.
+- Maintain good operational hygiene with meaningful logs and diagnostics on important paths, and add more for risky systems.
+- Use feature work as an opportunity for meaningful surrounding cleanup when the added refactoring clearly improves the change.
+
+## Debugging Defaults
+
+- Start with the fastest trustworthy signal rather than forcing a single debugging order.
+- Lean on logs and traces heavily before guessing.
+- During live or user-impacting incidents, stabilize first and diagnose more deeply after impact is reduced.
+- Prefer reversible mitigations such as rollbacks, flags, or partial disablement when risk is high.
+- Add regression tests for higher-risk or recurring bugs rather than treating every fix as a mandatory test addition.
+- Explain root cause clearly by connecting symptom, cause, and why the fix works.
+- Avoid temporary compromises unless there is no safer path.
+- Bundle observability improvements with medium or high-risk bug fixes when they would make future diagnosis easier.
+
+## Documentation Defaults
+
+- Treat documentation as part of most meaningful implementation work unless it is clearly unnecessary.
+- Default to practical onboarding that includes prerequisites, setup steps, validation, and common gotchas.
+- Create or update ADRs for major technical decisions and meaningful pattern shifts.
+- Write concise, audience-aware change summaries that call out user impact when relevant.
+- Maintain strong API and integration documentation by default for meaningful backend or interface work.
+- Prefer examples, snippets, and commands in places where they reduce ambiguity and improve adoption.
+- Update docs for any meaningful user-facing, setup, or team workflow change.
+- Bias toward concise documentation for reference material and more complete guidance for onboarding and operational content.
+
+## UI/UX Defaults
+
+- Prefer reuse of existing design-system components and patterns, but allow custom patterns when they clearly improve the experience.
+- Do not assume extra accessibility work by default beyond the repository or task requirements unless the task calls for it.
+- Design responsively for both desktop and mobile by default.
+- Reuse components when they fit well, and create new abstractions when they are likely to matter again.
+- Hold interface copy to a highly polished product-copy standard by default.
+- Use motion and visual flourish actively enough to make interfaces feel premium.
+- Bias toward bold, distinctive UI within reason rather than purely conservative continuity.
+- Treat UI work as incomplete until important states, copy quality, polish, and edge cases are addressed.
+
+## Marketing Defaults
+
+- Prioritize a mixed audience with a lean toward technical and product-savvy readers.
+- Use a premium, distinctive, and persuasive voice.
+- Keep marketing claims persuasive but grounded in real features and outcomes.
+- Default to a fuller launch kit when marketing work is requested: release notes, launch copy, landing page sections, and social or email variants as appropriate.
+- Balance launch messaging with evergreen discoverability, but do not let SEO weaken clarity.
+- Favor sharp, polished product copy with strong differentiation and clear calls to action.
+- Frame positioning conservatively around real value rather than aggressive comparative claims.
+- Prefer clear, action-oriented CTAs without heavy urgency.
+
+## Brainstorming Defaults
+
+- Favor breadth first when generating ideas.
+- Generate three options by default before recommending one.
+- Compare ideas primarily through user value, differentiation, and implementation realism.
+- Prioritize roadmap or opportunity choices through strategic fit, user value, and implementation cost.
+- Balance innovation with execution realism and require a believable path to implementation.
+- Use a short-to-medium horizon with practical sequencing for roadmap framing.
+- Turn brainstorming into a scoped implementation plan once a preferred option is selected.
+- Do not filter ideas out too early; raise concerns and explore alternatives that may offer more value before narrowing.

Dockerfile

@@ -0,0 +1,38 @@
+FROM node:24-alpine AS builder
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+# ---
+
+FROM node:24-alpine AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV DATA_DIR=/app/data
+ENV UPLOADS_DIR=/app/uploads
+ENV PORT=3000
+
+RUN apk add --no-cache curl
+
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/views ./views
+
+RUN mkdir -p /app/data /app/uploads/models /app/uploads/pdfs /app/uploads/thumbnails /app/uploads/brand
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+  CMD curl -f http://localhost:3000/health || exit 1
+
+CMD ["node", "dist/server/app.js"]

INSTALL.md

@@ -0,0 +1,105 @@
+# Install and Copy Guide
+
+Use this guide to copy the instruction suite into another repository without bloating the destination or confusing the agent.
+
+## Recommended Install
+
+Copy these items into the target repository root:
+
+- `AGENTS.md`
+- `DEPLOYMENT-PROFILE.md`
+- `SKILLS.md`
+- `PROJECT-PROFILE-WORKBOOK.md`
+- `ROUTING-EXAMPLES.md`
+- `hubs/`
+- `skills/`
+
+Optional:
+
+- `README.md` if you want human-facing explanation of the bundle in the destination repo
+
+## Fast Copy Workflow
+
+From this repository root, copy the suite into another repo root while excluding `.git`:
+
+```powershell
+Copy-Item AGENTS.md,DEPLOYMENT-PROFILE.md,SKILLS.md,PROJECT-PROFILE-WORKBOOK.md,ROUTING-EXAMPLES.md -Destination <target-repo>
+Copy-Item hubs -Destination <target-repo> -Recurse
+Copy-Item skills -Destination <target-repo> -Recurse
+```
+
+If you also want the explanatory readme:
+
+```powershell
+Copy-Item README.md -Destination <target-repo>
+```
+
+## Prefill Workflow
+
+Before deployment:
+
+1. Fill out `PROJECT-PROFILE-WORKBOOK.md`.
+2. Translate the answers into agent-facing defaults in `DEPLOYMENT-PROFILE.md`.
+3. Keep the deployment profile concise so it can be read early without wasting context.
+4. Copy the suite with the filled-in deployment profile included.
+
+At runtime:
+
+1. The agent reads `AGENTS.md`.
+2. The agent reads `DEPLOYMENT-PROFILE.md` if it is filled in.
+3. The agent reads `SKILLS.md`.
+4. The agent opens the relevant hub and specialized skill files only as needed.
+
+## Minimal Install
+
+If the target repository wants the smallest useful setup, copy:
+
+- `AGENTS.md`
+- `DEPLOYMENT-PROFILE.md`
+- `SKILLS.md`
+- `hubs/`
+- only the skill files the team expects to use often
+
+Good minimal baseline:
+
+- `skills/software/repo-exploration.md`
+- `skills/software/feature-implementation.md`
+- `skills/software/test-strategy.md`
+- `skills/software/code-review.md`
+- `skills/debugging/bug-triage.md`
+- `skills/debugging/debugging-workflow.md`
+- `skills/documentation/technical-docs.md`
+- `skills/ui-ux/ux-review.md`
+
+## How To Customize Safely
+
+- Keep `AGENTS.md` short and stable; put detail in hubs and skill files.
+- Add repo-specific instructions near the top of `AGENTS.md` or in existing repo instruction files.
+- Treat `DEPLOYMENT-PROFILE.md` as the canonical place for staged build, tool, environment, and workflow defaults.
+- Prefer editing hub routing before adding more root-level rules.
+- Add new skill files only when they introduce a distinct workflow, risk area, or deliverable.
+- If two skills overlap heavily, merge them or make the routing distinction explicit.
+
+## Context Limit Guidance
+
+- Do not instruct the agent to load the entire `skills/` tree on every task.
+- Keep the default path to one hub plus two to four specialized skills.
+- Reserve four to six skills for large cross-functional tasks.
+- Use the routing examples to confirm the suite still routes clearly after customization.
+
+## Updating The Bundle
+
+- Pull improvements from this source repository into destination repos periodically.
+- Refill the workbook and refresh the deployment profile when your preferred defaults change materially.
+- Review local customizations before overwriting shared files.
+- If a destination repo has stronger local conventions, keep those and treat this suite as the fallback layer.
+
+## Suggested Verification After Copying
+
+Check that the destination repo can answer these questions clearly:
+
+1. Where does the agent start? `AGENTS.md`
+2. Where does the agent get preloaded defaults? `DEPLOYMENT-PROFILE.md`
+3. Where does the agent look for available skills? `SKILLS.md`
+4. How does the agent decide what to read next? Deployment profile, hubs, and routing examples
+5. Does the repo still prioritize local instructions over the generic bundle? It should

PROJECT-PROFILE-WORKBOOK.md

@@ -0,0 +1,207 @@
+# Project Profile Workbook
+
+Fill out this workbook once before deployment when you want the suite to ship with pre-staged defaults for build, tools, environment, workflow, and quality preferences.
+
+This version has been completed and should act as the human-readable source behind [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md).
+
+## How To Use This Workbook
+
+- Keep answers concise and specific.
+- Prefer durable defaults over task-specific preferences.
+- If a question does not matter for your projects, write `No strong preference`.
+- If your answer depends on project type, note the default and the main exception.
+- Treat this workbook as the source for pre-deployment staging, not a runtime questionnaire.
+
+## Global Defaults
+
+### 1. What repository types should this suite optimize for by default?
+Answer: Full-stack web apps.
+
+### 2. What operating systems, shells, and local environments should the agent assume first?
+Answer: Windows and PowerShell for local development. Keep Linux, Docker, and Unraid deployment realities in mind.
+
+### 3. What package managers, build tools, and task runners should the agent prefer when multiple options exist?
+Answer: Compatibility-first defaults and standard stack tooling.
+
+### 4. Which languages, runtimes, or frameworks should get first-class preference across deployments?
+Answer: Node and TypeScript first for application work, with Python acceptable for tooling and automation.
+
+### 5. What is your default testing philosophy before considering work complete?
+Answer: Run the most relevant local tests for the changed area by default, and broaden verification for risky changes.
+
+### 6. How cautious should the agent be about asking questions versus making reasonable assumptions?
+Answer: Ask-first when product intent or change risk is unclear.
+
+### 7. What documentation should usually be updated when behavior, setup, or workflows change?
+Answer: Readmes, Unraid install docs, roadmaps, and shipped summaries are all important and should usually be updated when changes matter.
+
+### 8. What UX and polish bar should the suite assume for user-facing changes?
+Answer: High polish by default.
+
+### 9. What release, rollout, and communication expectations should be standard?
+Answer: Provide a concise change summary by default and note rollout or migration impact when relevant.
+
+### 10. What kinds of risk should the suite optimize hardest against?
+Answer: Regressions and broken behavior.
+
+## Software Development Defaults
+
+### 1. What architecture style or system design bias should be the default?
+Answer: Favor modular boundaries and cleaner separation early.
+
+### 2. How should the suite balance frontend, backend, and full-stack execution by default?
+Answer: Full-stack by default.
+
+### 3. Which frameworks, libraries, or implementation patterns should be preferred first?
+Answer: Prefer mainstream modern patterns for the stack.
+
+### 4. What database and persistence assumptions should the agent make?
+Answer: Relational database first.
+
+### 5. How conservative should migration and schema-change work be?
+Answer: Be careful, but do not overengineer small schema changes.
+
+### 6. What dependency upgrade strategy should be assumed?
+Answer: Prefer small, safe, frequent upgrades with focused validation.
+
+### 7. What performance bar should the suite assume by default?
+Answer: Be proactive about performance on critical paths.
+
+### 8. What minimum security baseline should be applied to code changes?
+Answer: Basic secure defaults only: validate input, handle secrets safely, and respect auth boundaries.
+
+### 9. What observability and operability expectations should be normal?
+Answer: Good operational hygiene with meaningful logs and diagnostics for important paths.
+
+### 10. How aggressive should the agent be about refactoring and technical debt reduction while doing feature work?
+Answer: Use feature work as an opportunity to improve surrounding structure meaningfully when it helps the change.
+
+## Debugging Defaults
+
+### 1. Should debugging start with reproduction first, code inspection first, or whichever is fastest to verify?
+Answer: Use whichever path gives the fastest trustworthy signal.
+
+### 2. What logs, traces, or diagnostics should the agent expect to consult before guessing?
+Answer: Lean on logs and traces first.
+
+### 3. How should the agent behave during live or user-impacting incidents?
+Answer: Stabilize first, then diagnose more deeply.
+
+### 4. What is the preferred rollback, mitigation, or feature-flag strategy when risk is high?
+Answer: Prefer reversible mitigations such as flags, rollbacks, or partial disablement.
+
+### 5. How strongly should the agent try to add or update tests when fixing bugs?
+Answer: Add tests for higher-risk or recurring bugs.
+
+### 6. What level of root-cause explanation should be standard after a fix?
+Answer: Clearly explain cause, symptom, and why the fix works.
+
+### 7. What tradeoffs are acceptable when stabilizing an issue quickly?
+Answer: Avoid temporary compromises unless there is no safer path.
+
+### 8. When should observability improvements be bundled with a bug fix?
+Answer: For most medium or high-risk bugs, add enough signal to help next time.
+
+## Documentation Defaults
+
+### 1. How strongly should the suite treat documentation as part of normal implementation work?
+Answer: Docs are part of most meaningful changes unless clearly unnecessary.
+
+### 2. What onboarding depth should be the default for new repos or contributor workflows?
+Answer: Practical onboarding with prerequisites, setup steps, validation, and common gotchas.
+
+### 3. When should architecture decision records be created or updated?
+Answer: For major decisions and meaningful pattern shifts.
+
+### 4. What release-note or change-summary style should be standard?
+Answer: Concise, audience-aware summaries with user impact called out when relevant.
+
+### 5. What level of API or integration documentation is expected by default?
+Answer: Strong API and integration documentation by default.
+
+### 6. How much should examples, snippets, or command samples be favored in docs?
+Answer: Prefer examples for setup, APIs, and workflows where ambiguity hurts adoption.
+
+### 7. What documentation updates should be mandatory after behavior or workflow changes?
+Answer: Update docs for any meaningful user-facing, setup, or team workflow change.
+
+### 8. What types of documentation should be concise versus comprehensive?
+Answer: Balanced. Keep reference content concise and onboarding or operational content more complete.
+
+## UI/UX Defaults
+
+### 1. How strict should design-system adherence be by default?
+Answer: Strong preference for reuse, but custom patterns are acceptable when they clearly improve the experience.
+
+### 2. What accessibility baseline should every user-facing change meet?
+Answer: Do not assume extra accessibility work by default unless requested.
+
+### 3. What responsive behavior should be assumed for new or updated UI?
+Answer: Responsive by default for desktop and mobile.
+
+### 4. How strongly should the agent favor component reuse over local implementation?
+Answer: Reuse when it fits well, and create new abstractions only when they are likely to matter again.
+
+### 5. What clarity and copy standards should be assumed for interface text?
+Answer: Highly polished product-copy quality by default.
+
+### 6. How much motion, animation, or visual flourish is appropriate by default?
+Answer: Use motion and flourish actively enough to make the interface feel premium.
+
+### 7. Should the suite bias toward bold, distinctive UI or conservative continuity with existing patterns?
+Answer: Bold and distinctive by default, within reason.
+
+### 8. How detailed should UI work be before it is considered ready?
+Answer: High completeness with strong state coverage, copy quality, polish, and edge-case handling.
+
+## Marketing Defaults
+
+### 1. Which audience should marketing and messaging defaults prioritize first?
+Answer: Mixed audience, leaning technical and product-savvy.
+
+### 2. What voice and tone should be the baseline?
+Answer: Premium, distinctive, and persuasive.
+
+### 3. What level of proof, specificity, or technical grounding should marketing claims include?
+Answer: Claims should be persuasive but grounded in real features and outcomes.
+
+### 4. What launch-content formats should be standard by default?
+Answer: Broader launch kit: release notes, launch copy, landing page sections, and social or email variants.
+
+### 5. How important is SEO and evergreen discoverability relative to launch messaging?
+Answer: Balance both, but do not let SEO weaken clarity.
+
+### 6. What product-copy style should be the default?
+Answer: Strong product-copy polish with sharper differentiation and CTA energy.
+
+### 7. How should the suite frame differentiation and positioning?
+Answer: Conservative positioning that focuses on real value rather than aggressive comparison.
+
+### 8. What types of calls to action should be preferred?
+Answer: Clear, action-oriented CTAs without heavy urgency.
+
+## Brainstorming Defaults
+
+### 1. Should idea generation favor breadth, speed, novelty, practicality, or a specific balance?
+Answer: Favor breadth first.
+
+### 2. How many options should the agent generate by default before recommending one?
+Answer: Three options by default.
+
+### 3. What criteria should be used most often to score or compare ideas?
+Answer: User value, differentiation, and implementation realism.
+
+### 4. What prioritization method should be the default for roadmap or opportunity choices?
+Answer: Strategic fit, user value, and implementation cost.
+
+### 5. How should innovation be balanced against implementation realism?
+Answer: Balanced, but require a believable path to execution.
+
+### 6. What kind of roadmap framing should be standard?
+Answer: Short-to-medium horizon with practical sequencing.
+
+### 7. When should brainstorming output turn into a scoped implementation plan?
+Answer: Usually after a preferred option is selected.
+
+### 8. What types of ideas should usually be filtered out early?
+Answer: Do not filter too early. Raise concerns and explore alternatives with more value before narrowing.

README.md

@@ -0,0 +1,47 @@
+# Drop-In Agent Instruction Suite
+
+This repository is a portable markdown instruction pack for coding agents.
+
+Copy these files into another repository to give the agent:
+- a root `AGENTS.md` entrypoint,
+- a central skill index,
+- category hubs for routing,
+- specialized skill files for common software, docs, UX, marketing, and ideation tasks.
+
+## Structure
+
+- `AGENTS.md` - base instructions and routing rules
+- `DEPLOYMENT-PROFILE.md` - agent-readable prefilled deployment defaults
+- `INSTALL.md` - copy and customization guide for other repositories
+- `PROJECT-PROFILE-WORKBOOK.md` - one-time questionnaire for staging defaults
+- `SKILLS.md` - canonical skill index
+- `ROUTING-EXAMPLES.md` - representative prompt-to-skill routing examples
+- `hubs/` - category-level routing guides
+- `skills/` - specialized reusable skill files
+
+## Design Goals
+
+- Plain markdown only
+- Cross-agent portability
+- Implementation-first defaults
+- On-demand skill loading instead of loading everything every session
+- Context-efficient routing for large skill libraries
+- Prefilled deployment defaults without per-install questioning
+- Repo-local instructions take precedence over this bundle
+
+## Intended Workflow
+
+1. The agent reads `AGENTS.md`.
+2. The agent reads `DEPLOYMENT-PROFILE.md` when it is filled in.
+3. The agent checks `SKILLS.md`.
+4. The agent opens only the relevant hub and skill files for the task.
+5. The agent combines multiple skills when the task spans several domains.
+
+## Core Categories
+
+- Software development
+- Debugging
+- Documentation
+- UI/UX
+- Marketing
+- Brainstorming

ROUTING-EXAMPLES.md

@@ -0,0 +1,84 @@
+# Routing Examples
+
+Use these examples to validate that the suite routes clearly from `AGENTS.md` to the right hub files and specialized skills.
+
+In deployments with a filled-in [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md), the agent should read that file after `AGENTS.md` and before opening hubs or skills.
+
+## Representative Prompts
+
+### Fix a failing backend test and explain the root cause
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Debugging Hub](./hubs/debugging.md)
+- Use [Bug Triage](./skills/debugging/bug-triage.md)
+- Use [Debugging Workflow](./skills/debugging/debugging-workflow.md)
+- Add [API and Backend Work](./skills/software/api-backend.md)
+- Add [Test Strategy](./skills/software/test-strategy.md)
+
+### Build a new UI settings page with good UX and copy
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Software Development Hub](./hubs/software-development.md)
+- Use [Feature Implementation](./skills/software/feature-implementation.md)
+- Use [Frontend UI Implementation](./skills/software/frontend-ui-implementation.md)
+- Add [UI/UX Hub](./hubs/ui-ux.md)
+- Use [UX Review](./skills/ui-ux/ux-review.md)
+- Add [Product Copy](./skills/marketing/product-copy.md)
+
+### Write release notes and update onboarding docs for this feature
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Documentation Hub](./hubs/documentation.md)
+- Use [Release and Change Summary](./skills/software/release-change-summary.md)
+- Use [Onboarding Documentation](./skills/documentation/onboarding-docs.md)
+- Add [Technical Documentation](./skills/documentation/technical-docs.md) if setup or behavior changed
+
+### Brainstorm three product directions and turn the best one into a scoped implementation plan
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Brainstorming Hub](./hubs/brainstorming.md)
+- Use [Ideation](./skills/brainstorming/ideation.md)
+- Use [Structured Brainstorming](./skills/brainstorming/structured-brainstorming.md)
+- Add [Repository Exploration](./skills/software/repo-exploration.md) if the plan must align to an existing codebase
+- Add [Feature Implementation](./skills/software/feature-implementation.md) for implementation-ready shaping
+
+### Review this PR for bugs, regressions, and missing tests
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Software Development Hub](./hubs/software-development.md)
+- Use [Code Review](./skills/software/code-review.md)
+- Add [Test Strategy](./skills/software/test-strategy.md)
+
+### Draft launch messaging for a developer tool feature
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Marketing Hub](./hubs/marketing.md)
+- Use [Messaging and Positioning](./skills/marketing/messaging-positioning.md)
+- Use [Marketing Content](./skills/marketing/marketing-content.md)
+- Add [Technical Documentation](./skills/documentation/technical-docs.md) if claims need implementation-grounded detail
+
+### Plan a risky framework upgrade without derailing feature delivery
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Software Development Hub](./hubs/software-development.md)
+- Use [Dependency Lifecycle Management](./skills/software/dependency-lifecycle.md)
+- Add [Test Strategy](./skills/software/test-strategy.md)
+- Add [Maintenance and Technical Debt Planning](./skills/software/maintenance-technical-debt.md)
+- Add [Release and Change Summary](./skills/software/release-change-summary.md) if rollout communication matters
+
+### Respond to a live production issue and leave the system easier to diagnose next time
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Debugging Hub](./hubs/debugging.md)
+- Use [Incident Response and Stabilization](./skills/debugging/incident-response-stabilization.md)
+- Use [Debugging Workflow](./skills/debugging/debugging-workflow.md)
+- Add [Observability and Operability](./skills/software/observability-operability.md)
+- Add [Bug Triage](./skills/debugging/bug-triage.md) if reproduction or impact framing is still loose

SKILLS.md

@@ -0,0 +1,91 @@
+# Skill Index
+
+This file is the canonical registry for the instruction suite. Read this index after `AGENTS.md` and the deployment profile, then open only the hub and skill files needed for the current task.
+
+## Skill Contract
+
+Every skill file follows the same structure:
+- `Purpose`
+- `When to use`
+- `Inputs to gather`
+- `How to work`
+- `Output expectations`
+- `Quality checklist`
+- `Handoff notes`
+
+## Loading Guidance
+
+- If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) is filled in, treat it as the default preference layer before applying generic skill guidance.
+- Start narrow: one hub plus the smallest set of specialized skills that covers the task.
+- Typical task size: two to four skills.
+- Larger, cross-functional tasks may need four to six skills, but only when each one adds a distinct concern.
+- Prefer high-leverage skills that shape implementation quality over collecting adjacent but redundant guidance.
+- When in doubt, prioritize repository exploration, implementation/debugging, testing, and one domain-specific skill.
+
+## Category Hubs
+
+- [Software Development](./hubs/software-development.md)
+- [Debugging](./hubs/debugging.md)
+- [Documentation](./hubs/documentation.md)
+- [UI/UX](./hubs/ui-ux.md)
+- [Marketing](./hubs/marketing.md)
+- [Brainstorming](./hubs/brainstorming.md)
+
+## Specialized Skills
+
+### Software Development
+
+- [Architecture and System Design](./skills/software/architecture-system-design.md)
+- [Feature Implementation](./skills/software/feature-implementation.md)
+- [Refactoring](./skills/software/refactoring.md)
+- [Code Review](./skills/software/code-review.md)
+- [Test Strategy](./skills/software/test-strategy.md)
+- [API and Backend Work](./skills/software/api-backend.md)
+- [Database Migrations and Data Evolution](./skills/software/database-migrations.md)
+- [Dependency Lifecycle Management](./skills/software/dependency-lifecycle.md)
+- [Performance Optimization](./skills/software/performance-optimization.md)
+- [Security Review and Hardening](./skills/software/security-review-hardening.md)
+- [Observability and Operability](./skills/software/observability-operability.md)
+- [Maintenance and Technical Debt Planning](./skills/software/maintenance-technical-debt.md)
+- [Frontend UI Implementation](./skills/software/frontend-ui-implementation.md)
+- [Repository Exploration](./skills/software/repo-exploration.md)
+- [Release and Change Summary](./skills/software/release-change-summary.md)
+
+### Debugging
+
+- [Bug Triage](./skills/debugging/bug-triage.md)
+- [Debugging Workflow](./skills/debugging/debugging-workflow.md)
+- [Incident Response and Stabilization](./skills/debugging/incident-response-stabilization.md)
+
+### Documentation
+
+- [Architecture Decision Records](./skills/documentation/architecture-decision-records.md)
+- [Technical Documentation](./skills/documentation/technical-docs.md)
+- [Onboarding Documentation](./skills/documentation/onboarding-docs.md)
+
+### UI/UX
+
+- [UX Review](./skills/ui-ux/ux-review.md)
+- [Accessibility Review](./skills/ui-ux/accessibility-review.md)
+- [Design System and UI Consistency](./skills/ui-ux/design-system-consistency.md)
+
+### Marketing
+
+- [Product Copy](./skills/marketing/product-copy.md)
+- [Marketing Content](./skills/marketing/marketing-content.md)
+- [Messaging and Positioning](./skills/marketing/messaging-positioning.md)
+- [Content Strategy and SEO](./skills/marketing/content-strategy-seo.md)
+
+### Brainstorming
+
+- [Ideation](./skills/brainstorming/ideation.md)
+- [Structured Brainstorming](./skills/brainstorming/structured-brainstorming.md)
+- [Roadmap and Opportunity Prioritization](./skills/brainstorming/roadmap-opportunity-prioritization.md)
+
+## Quick Routing Hints
+
+- If the task changes code, start with the software development hub.
+- If the task starts from a defect, regression, failing test, or unclear breakage, add debugging skills.
+- If the task changes how people use, adopt, or understand the product, add documentation and possibly UX or marketing skills.
+- If the task asks for options, concepts, or strategic directions before execution, use brainstorming skills.
+- If the task affects long-term system health, look for architecture, security, performance, observability, dependency, or maintenance skills before loading more tactical ones.

docker-compose.yml

@@ -0,0 +1,35 @@
+services:
+  stepview:
+    build: .
+    container_name: stepview
+    restart: unless-stopped
+    ports:
+      - "${PORT:-3000}:3000"
+    volumes:
+      - ./data:/app/data
+      - ./uploads:/app/uploads
+    environment:
+      NODE_ENV: production
+      # node:sqlite requires this flag on Node 22; not needed on Node 24+
+      # NODE_OPTIONS: --experimental-sqlite
+      PORT: 3000
+      DATA_DIR: /app/data
+      UPLOADS_DIR: /app/uploads
+      # Change these before deploying
+      ADMIN_USER: ${ADMIN_USER:-admin}
+      ADMIN_PASS: ${ADMIN_PASS:-changeme}
+      SESSION_SECRET: ${SESSION_SECRET:-change-this-secret-in-production}
+      BASE_URL: ${BASE_URL:-http://localhost:3000}
+      MAX_FILE_MB: ${MAX_FILE_MB:-500}
+      # Bootstrap branding (can be changed later in Admin > Settings)
+      BRAND_NAME: ${BRAND_NAME:-StepView}
+      BRAND_ACCENT: ${BRAND_ACCENT:-#3b82f6}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    labels:
+      net.unraid.docker.managed: "true"
+      net.unraid.docker.icon: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/files.svg"

hubs/brainstorming.md

@@ -0,0 +1,25 @@
+# Brainstorming Hub
+
+Use this hub when the task is to generate options, explore solution space, compare directions, or turn rough ideas into structured next steps.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains brainstorming defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- The user wants concepts, options, or strategic directions
+- Requirements are early-stage and need shaping
+- A promising idea needs to become a scoped plan
+- The team wants alternatives before implementation
+
+## Skill Routing
+
+- [Ideation](../skills/brainstorming/ideation.md) for broad option generation and concept creation
+- [Structured Brainstorming](../skills/brainstorming/structured-brainstorming.md) for narrowing, comparing, scoring, and turning ideas into action
+- [Roadmap and Opportunity Prioritization](../skills/brainstorming/roadmap-opportunity-prioritization.md) for sequencing initiatives, balancing impact versus effort, and choosing what should happen next
+
+## Common Combinations
+
+- Product concepting: ideation + messaging/positioning
+- Solution design: ideation + structured brainstorming + repository exploration
+- From ideas to build plan: structured brainstorming + feature implementation + test strategy
+- Long-range planning: roadmap and opportunity prioritization + maintenance and technical debt planning + architecture and system design

hubs/debugging.md

@@ -0,0 +1,27 @@
+# Debugging Hub
+
+Use this hub for work that begins with a defect, regression, failing test, production issue, or confusing system behavior.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains debugging defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- A test is failing and the cause is unclear
+- A user-reported bug needs reproduction and triage
+- The system behaves inconsistently across environments or inputs
+- A suspected regression needs careful isolation
+
+## Start With
+
+- [Bug Triage](../skills/debugging/bug-triage.md) to define the problem, impact, environment, and reproduction path
+- [Debugging Workflow](../skills/debugging/debugging-workflow.md) to isolate root cause and verify a fix
+
+## Combine With
+
+- [API and Backend Work](../skills/software/api-backend.md) when the issue is server-side or data-related
+- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) when the issue is client-side or interaction-related
+- [Test Strategy](../skills/software/test-strategy.md) when the fix needs coverage
+- [Release and Change Summary](../skills/software/release-change-summary.md) when the resolution should be communicated clearly
+- [Incident Response and Stabilization](../skills/debugging/incident-response-stabilization.md) when the issue is live, user-impacting, or needs temporary containment before a full fix
+- [Observability and Operability](../skills/software/observability-operability.md) when logs, metrics, traces, or alerting gaps block diagnosis
+- [Performance Optimization](../skills/software/performance-optimization.md) when the problem is latency, throughput, memory, or rendering related

hubs/documentation.md

@@ -0,0 +1,26 @@
+# Documentation Hub
+
+Use this hub when the task changes how people understand, adopt, operate, or maintain the product.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains documentation defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- Write or update technical documentation
+- Improve onboarding or contributor guidance
+- Create release notes or change summaries
+- Align docs with code or product changes
+
+## Skill Routing
+
+- [Architecture Decision Records](../skills/documentation/architecture-decision-records.md) for capturing meaningful technical choices, tradeoffs, and why a direction was selected
+- [Technical Documentation](../skills/documentation/technical-docs.md) for architecture, APIs, workflows, operational guidance, and usage docs
+- [Onboarding Documentation](../skills/documentation/onboarding-docs.md) for setup guides, contributor onboarding, first-run experience, and internal enablement
+- [Release and Change Summary](../skills/software/release-change-summary.md) for release notes, changelog writing, and rollout explanations
+
+## Common Combinations
+
+- New feature: technical docs + release/change summary
+- Developer experience improvement: onboarding docs + technical docs
+- Product launch: release/change summary + messaging/positioning + marketing content
+- Long-lived architecture change: architecture and system design + architecture decision records + technical docs

hubs/marketing.md

@@ -0,0 +1,26 @@
+# Marketing Hub
+
+Use this hub for external-facing product language, launch assets, positioning, and persuasive communication.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains marketing defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- Draft launch messaging or feature announcements
+- Improve website or product marketing copy
+- Clarify product differentiation and audience fit
+- Create marketing assets tied to engineering or product changes
+
+## Skill Routing
+
+- [Product Copy](../skills/marketing/product-copy.md) for UI-adjacent language, concise product text, and conversion-oriented wording
+- [Marketing Content](../skills/marketing/marketing-content.md) for launch posts, feature pages, emails, social copy, and content drafts
+- [Messaging and Positioning](../skills/marketing/messaging-positioning.md) for audience, value proposition, differentiation, and narrative framing
+- [Content Strategy and SEO](../skills/marketing/content-strategy-seo.md) for durable organic content, search intent alignment, and content planning
+
+## Common Combinations
+
+- Feature launch: messaging/positioning + marketing content + release/change summary
+- Landing page refresh: product copy + messaging/positioning + UX review
+- Developer tool announcement: marketing content + technical docs + messaging/positioning
+- Evergreen growth work: content strategy and SEO + messaging/positioning + technical docs

hubs/software-development.md

@@ -0,0 +1,44 @@
+# Software Development Hub
+
+Use this hub for implementation-focused software work: features, refactors, code review, tests, backend changes, frontend changes, and release communication tied to engineering output.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains software defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- Build or modify product functionality
+- Improve maintainability or architecture
+- Review existing code for bugs, regressions, or missing tests
+- Plan or add verification coverage
+- Explore an unfamiliar codebase before changing it
+
+## Start With
+
+- [Repository Exploration](../skills/software/repo-exploration.md) for unfamiliar codebases or vague requests
+- [Feature Implementation](../skills/software/feature-implementation.md) for net-new behavior or substantial changes
+
+## Skill Routing
+
+- [Architecture and System Design](../skills/software/architecture-system-design.md) for major system changes, design tradeoffs, and long-lived technical direction
+- [Refactoring](../skills/software/refactoring.md) for structure improvements without intended behavior changes
+- [Code Review](../skills/software/code-review.md) for finding bugs, regressions, risky assumptions, and missing coverage
+- [Test Strategy](../skills/software/test-strategy.md) for designing, expanding, or evaluating verification
+- [API and Backend Work](../skills/software/api-backend.md) for services, storage, schema, integration, and server-side logic
+- [Database Migrations and Data Evolution](../skills/software/database-migrations.md) for schema changes, backfills, compatibility windows, and rollout-safe data transitions
+- [Dependency Lifecycle Management](../skills/software/dependency-lifecycle.md) for upgrades, dependency risk reduction, and ecosystem maintenance
+- [Performance Optimization](../skills/software/performance-optimization.md) for latency, throughput, rendering, and resource-efficiency work
+- [Security Review and Hardening](../skills/software/security-review-hardening.md) for auth, validation, secrets, exposure, and abuse resistance concerns
+- [Observability and Operability](../skills/software/observability-operability.md) for logging, metrics, traces, alerts, and operational readiness
+- [Maintenance and Technical Debt Planning](../skills/software/maintenance-technical-debt.md) for long-horizon cleanup, risk reduction, and sequencing work
+- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) for interfaces, interaction logic, and client-side UX execution
+- [Release and Change Summary](../skills/software/release-change-summary.md) for release notes, summaries, migration notes, and rollout communication
+
+## Common Combinations
+
+- New feature: repository exploration + feature implementation + test strategy + technical docs
+- Backend bug fix: bug triage + debugging workflow + API and backend work + release/change summary
+- UI feature: feature implementation + frontend UI implementation + UX review + product copy
+- PR review: code review + test strategy
+- Platform change: architecture and system design + API/backend work + observability and operability + technical docs
+- Risky upgrade: dependency lifecycle management + test strategy + release/change summary
+- Data model change: architecture and system design + database migrations and data evolution + API/backend work

hubs/ui-ux.md

@@ -0,0 +1,26 @@
+# UI/UX Hub
+
+Use this hub when the task depends on interface quality, interaction flow, usability, clarity, or user-facing content design.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains UI/UX defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- Review a screen, flow, or feature for UX weaknesses
+- Improve copy, hierarchy, clarity, or task completion
+- Implement or revise UI behavior with usability in mind
+
+## Skill Routing
+
+- [UX Review](../skills/ui-ux/ux-review.md) for critique, heuristics, friction detection, and recommendations
+- [Accessibility Review](../skills/ui-ux/accessibility-review.md) for inclusive interaction quality, keyboard support, semantics, contrast, and assistive-technology readiness
+- [Design System and UI Consistency](../skills/ui-ux/design-system-consistency.md) for component reuse, visual consistency, and scalable UI patterns
+- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) for shipping the UI changes
+- [Product Copy](../skills/marketing/product-copy.md) when labels, empty states, CTAs, or in-product messaging matter
+
+## Common Combinations
+
+- New settings page: frontend UI implementation + UX review + product copy
+- Navigation cleanup: UX review + frontend UI implementation
+- Conversion-focused UI change: UX review + product copy + messaging/positioning
+- UI platform work: design system and UI consistency + frontend UI implementation + accessibility review

package.json

@@ -0,0 +1,41 @@
+{
+  "name": "stepview",
+  "version": "0.1.0",
+  "description": "Dockerized 3D CAD model viewer for STEP, STP, and STL files",
+  "scripts": {
+    "dev": "concurrently \"tsx watch src/server/app.ts\" \"vite build --watch\"",
+    "build": "tsc -p tsconfig.server.json && vite build",
+    "start": "node --disable-warning=ExperimentalWarning dist/server/app.js",
+    "clean": "rimraf dist public"
+  },
+  "dependencies": {
+    "bcryptjs": "^2.4.3",
+    "compression": "^1.8.1",
+    "dotenv": "^16.4.5",
+    "ejs": "^3.1.10",
+    "express": "^4.19.2",
+    "express-session": "^1.18.0",
+    "multer": "^1.4.5-lts.1",
+    "occt-import-js": "^0.0.23",
+    "slugify": "^1.6.6",
+    "three": "^0.184.0"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
+    "@types/compression": "^1.8.1",
+    "@types/ejs": "^3.1.5",
+    "@types/express": "^4.17.21",
+    "@types/express-session": "^1.18.0",
+    "@types/multer": "^1.4.11",
+    "@types/node": "^22.0.0",
+    "@types/three": "^0.184.0",
+    "autoprefixer": "^10.4.19",
+    "concurrently": "^8.2.2",
+    "postcss": "^8.4.38",
+    "rimraf": "^5.0.7",
+    "tailwindcss": "^3.4.3",
+    "tsx": "^4.10.5",
+    "typescript": "^5.4.5",
+    "vite": "^5.2.10"
+  }
+}

postcss.config.cjs

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

skills/brainstorming/ideation.md

@@ -0,0 +1,45 @@
+# Ideation
+
+## Purpose
+
+Generate strong options quickly without locking too early onto the first plausible idea.
+
+## When to use
+
+- The user wants multiple concepts, approaches, or product directions
+- Requirements are early and the solution space is still wide
+- A team needs creative alternatives before choosing a path
+- You want to escape local maxima in product or technical thinking
+
+## Inputs to gather
+
+- Goal, audience, constraints, and success criteria
+- What is already known, tried, or ruled out
+- Time, complexity, and implementation constraints
+- The desired balance of novelty versus practicality
+
+## How to work
+
+- Produce several meaningfully different options, not minor variations of one idea.
+- Cover a range from safer to bolder approaches when useful.
+- Make tradeoffs explicit so ideas are easy to compare.
+- Keep ideas concrete enough that someone can imagine implementation or execution.
+- Narrow only after the option space is genuinely explored.
+
+## Output expectations
+
+- Distinct options with concise descriptions
+- Tradeoffs, strengths, and risks for each option
+- A recommended direction when appropriate
+
+## Quality checklist
+
+- Options are genuinely different in mechanism or strategy.
+- Ideas respect the stated constraints.
+- Tradeoffs are visible rather than implied.
+- Recommendations, if given, follow from the comparison.
+
+## Handoff notes
+
+- Note whether the ideas are exploratory, implementation-ready, or need structured narrowing next.
+- Pair with structured brainstorming when the next step is selecting and shaping one path.

skills/brainstorming/roadmap-opportunity-prioritization.md

@@ -0,0 +1,45 @@
+# Roadmap and Opportunity Prioritization
+
+## Purpose
+
+Choose what to do next by comparing opportunities, maintenance work, and strategic bets against explicit decision criteria.
+
+## When to use
+
+- Too many plausible initiatives compete for limited time
+- Feature work and maintenance work need to be balanced
+- A team needs a more defensible roadmap discussion
+- Promising ideas need sequencing rather than more generation
+
+## Inputs to gather
+
+- Candidate initiatives or workstreams
+- Decision criteria such as impact, urgency, effort, risk reduction, or strategic fit
+- Dependencies, timing constraints, and team capacity
+- Evidence for expected payoff or avoided risk
+
+## How to work
+
+- Make prioritization criteria explicit before ranking work.
+- Compare user value, strategic value, and risk reduction together.
+- Treat maintenance and enabling work as first-class opportunities when they materially improve future delivery.
+- Distinguish what is urgent, what is high leverage, and what is merely attractive.
+- Produce a sequence that a team can actually act on.
+
+## Output expectations
+
+- Prioritized list or roadmap recommendation
+- Clear rationale for order and tradeoffs
+- Notes on what to defer, revisit, or validate next
+
+## Quality checklist
+
+- Priorities reflect stated criteria rather than intuition alone.
+- Sequencing respects dependencies and capacity.
+- Lower-priority items are deferred for a reason, not forgotten accidentally.
+- Maintenance work is evaluated on outcomes, not optics.
+
+## Handoff notes
+
+- Note what new evidence would most change the ranking.
+- Pair with maintenance and technical debt planning or structured brainstorming when the decision needs deeper shaping.

skills/brainstorming/structured-brainstorming.md

@@ -0,0 +1,45 @@
+# Structured Brainstorming
+
+## Purpose
+
+Turn rough ideas into decision-ready options by comparing them systematically, narrowing intelligently, and shaping the chosen direction into actionable next steps.
+
+## When to use
+
+- Many ideas exist and the team needs a clear recommendation
+- A promising concept needs scoping before implementation
+- Tradeoffs need to be surfaced explicitly
+- The next step is choosing, sequencing, or planning rather than generating more ideas
+
+## Inputs to gather
+
+- Candidate ideas or possible approaches
+- Decision criteria such as impact, effort, risk, speed, or strategic fit
+- Constraints on time, team, technical feasibility, or audience needs
+- Any assumptions that materially change the choice
+
+## How to work
+
+- Define the decision criteria before ranking options.
+- Compare options on the criteria that actually matter for the request.
+- Remove weak options quickly once the reason is clear.
+- Turn the selected direction into a scoped set of next steps or a buildable outline.
+- Keep the analysis proportional; do not over-formalize simple decisions.
+
+## Output expectations
+
+- Clear comparison of options
+- Recommended direction with reasoning
+- A scoped next-step plan or action outline
+
+## Quality checklist
+
+- Decision criteria are explicit and relevant.
+- The recommendation follows from the comparison rather than preference alone.
+- The chosen path is actionable, not just inspirational.
+- Key assumptions are visible.
+
+## Handoff notes
+
+- Note what would most likely change the recommendation.
+- Pair with feature implementation, repo exploration, or messaging skills when moving from choice to execution.

skills/debugging/bug-triage.md

@@ -0,0 +1,46 @@
+# Bug Triage
+
+## Purpose
+
+Frame a defect clearly before or during debugging so the team understands impact, reproduction, suspected scope, and next actions.
+
+## When to use
+
+- A bug report arrives with incomplete detail
+- A failing test or regression needs initial framing
+- Multiple issues compete for attention and severity matters
+- You need a reliable reproduction path before deeper debugging
+
+## Inputs to gather
+
+- Reported symptoms, expected behavior, and actual behavior
+- Reproduction steps, environment, and frequency
+- User impact, severity, and likely affected surfaces
+- Recent changes, logs, or tests that may be related
+
+## How to work
+
+- Turn vague symptoms into a concrete problem statement.
+- Reproduce the issue when possible and tighten the reproduction steps.
+- Separate confirmed facts from assumptions.
+- Estimate impact and likely blast radius before diving into fixes.
+- Identify the next best debugging step if root cause is not yet known.
+
+## Output expectations
+
+- Clear bug statement and reproduction status
+- Impact and severity assessment
+- Suspected scope or likely component area
+- Recommended next debugging or fix step
+
+## Quality checklist
+
+- The issue is described in observable terms rather than guesses.
+- Reproduction details are specific enough to be reused.
+- Impact is clear enough to prioritize intelligently.
+- Unknowns are named instead of hidden.
+
+## Handoff notes
+
+- Record environment details and whether the issue is deterministic, intermittent, or unconfirmed.
+- Pair with debugging workflow once the problem is framed well enough to investigate deeply.

skills/debugging/debugging-workflow.md

@@ -0,0 +1,46 @@
+# Debugging Workflow
+
+## Purpose
+
+Find root cause efficiently and verify fixes with a disciplined workflow that avoids premature assumptions and shallow symptom treatment.
+
+## When to use
+
+- The defect is real but the cause is unclear
+- A failing test needs investigation
+- The system has inconsistent or environment-specific behavior
+- A regression may have multiple plausible causes
+
+## Inputs to gather
+
+- Reproduction path or failing signal
+- Relevant code paths, logs, traces, state transitions, and recent changes
+- Existing tests or ways to validate a hypothesis
+- Environment details that may influence behavior
+
+## How to work
+
+- Reproduce first when possible, then narrow scope by isolating the smallest failing path.
+- Form hypotheses from evidence, not instinct alone, and invalidate them aggressively.
+- Inspect boundaries: inputs, outputs, state mutations, async timing, external dependencies, and configuration.
+- Fix the root cause rather than only masking symptoms when feasible.
+- Re-run the original failing signal and add regression protection if appropriate.
+
+## Output expectations
+
+- Root cause explanation tied to evidence
+- Fix or recommended fix approach
+- Verification that the original issue is resolved
+- Remaining uncertainty, if any
+
+## Quality checklist
+
+- The explanation connects cause to symptom clearly.
+- The chosen fix addresses the real failure mechanism.
+- Verification includes the original failing path.
+- Regression protection is considered when the bug is likely to recur.
+
+## Handoff notes
+
+- Note whether the issue was fully reproduced, partially inferred, or fixed based on a probable cause.
+- Mention monitoring or follow-up checks if confidence is limited by environment or observability.

skills/debugging/incident-response-stabilization.md

@@ -0,0 +1,45 @@
+# Incident Response and Stabilization
+
+## Purpose
+
+Guide high-pressure response to live or high-impact issues by separating immediate stabilization from deeper root-cause correction.
+
+## When to use
+
+- A production issue is actively impacting users or operators
+- A regression needs containment before a complete fix is ready
+- The team needs a calm sequence for triage, mitigation, and follow-up
+- Communication and operational clarity matter as much as code changes
+
+## Inputs to gather
+
+- Current symptoms, severity, affected users, and timing
+- Available logs, metrics, alerts, dashboards, and recent changes
+- Safe rollback, feature flag, degrade, or traffic-shaping options
+- Stakeholders who need updates and what they need to know
+
+## How to work
+
+- Stabilize user impact first if a safe containment path exists.
+- Keep mitigation, diagnosis, and communication distinct but coordinated.
+- Prefer reversible steps under uncertainty.
+- Record what is confirmed versus assumed while the incident is active.
+- After stabilization, convert the incident into structured debugging and prevention work.
+
+## Output expectations
+
+- Stabilization plan or incident response summary
+- Clear mitigation status and next actions
+- Follow-up work for root cause, observability, and prevention
+
+## Quality checklist
+
+- User impact reduction is prioritized appropriately.
+- Risky irreversible changes are avoided under pressure.
+- Communication is clear enough for collaborators to act.
+- Post-incident follow-up is not lost after immediate recovery.
+
+## Handoff notes
+
+- Note what was mitigated versus actually fixed.
+- Pair with debugging workflow and observability once the system is stable enough for deeper work.

skills/documentation/architecture-decision-records.md

@@ -0,0 +1,45 @@
+# Architecture Decision Records
+
+## Purpose
+
+Capture significant technical decisions so future contributors understand what was chosen, why it was chosen, and what tradeoffs were accepted.
+
+## When to use
+
+- A meaningful architectural or platform choice has been made
+- Multiple alternatives were considered and context would otherwise be lost
+- A decision will affect future implementation, migration, or team habits
+- You want to prevent repeated re-litigation of the same tradeoff
+
+## Inputs to gather
+
+- The decision being made
+- Alternatives considered
+- Relevant constraints, drivers, and consequences
+- Current status: proposed, accepted, superseded, or rejected
+
+## How to work
+
+- Record the decision close to when it is made.
+- Keep the record concise but concrete enough to survive future context loss.
+- Explain why the selected option won, not just what it is.
+- Include consequences so future readers understand the cost of the choice.
+- Update or supersede older records rather than leaving conflicting guidance unresolved.
+
+## Output expectations
+
+- A crisp decision record with context, choice, alternatives, and consequences
+- Status that reflects whether the decision is still tentative or settled
+- Links to implementation or follow-up docs when useful
+
+## Quality checklist
+
+- The decision is clear and specific.
+- Alternatives and tradeoffs are visible.
+- Future readers can understand the reasoning without redoing the whole discussion.
+- The record stays short enough to remain useful.
+
+## Handoff notes
+
+- Reference the implementation, technical docs, or migration plan that operationalizes the decision.
+- Pair with architecture and system design for major system changes.

skills/documentation/onboarding-docs.md

@@ -0,0 +1,45 @@
+# Onboarding Documentation
+
+## Purpose
+
+Help new contributors or users become productive quickly by reducing ambiguity, setup friction, and missing context.
+
+## When to use
+
+- Improving setup or first-run guidance
+- Writing contributor onboarding docs
+- Creating "start here" guides for internal or external users
+- Simplifying confusing developer or product entry points
+
+## Inputs to gather
+
+- Current setup steps and prerequisites
+- Common failure points, hidden assumptions, and missing context
+- Existing onboarding flow and repository conventions
+- Intended audience: contributor, operator, customer, or teammate
+
+## How to work
+
+- Optimize for first success, not exhaustiveness.
+- Put prerequisites, setup order, and validation steps in the order a new person needs them.
+- Surface gotchas early rather than burying them after failures occur.
+- Use concrete commands, examples, and expected outcomes when they reduce confusion.
+- Trim insider jargon unless it is explained.
+
+## Output expectations
+
+- A cleaner onboarding path with clear first steps
+- Documentation that reduces setup ambiguity and dead ends
+- Helpful validation or troubleshooting guidance where needed
+
+## Quality checklist
+
+- A new person can tell where to start.
+- Steps are ordered logically and are easy to verify.
+- Prerequisites and common failures are not hidden.
+- The doc avoids assuming too much existing context.
+
+## Handoff notes
+
+- Note any setup steps you could not verify directly.
+- Pair with technical docs when onboarding depends on deeper conceptual explanation.

skills/documentation/technical-docs.md

@@ -0,0 +1,45 @@
+# Technical Documentation
+
+## Purpose
+
+Create or update documentation that helps developers, operators, or advanced users understand how the system works and how to use it correctly.
+
+## When to use
+
+- Updating docs after engineering changes
+- Writing usage guides, architecture notes, or operational docs
+- Explaining APIs, workflows, configuration, or system behavior
+- Improving stale or incomplete technical documentation
+
+## Inputs to gather
+
+- The current implementation and the user-visible workflow
+- Existing docs, terminology, and structure in the repo
+- Intended audience and their technical depth
+- Any setup steps, caveats, or common failure points
+
+## How to work
+
+- Document the real behavior of the system, not the hoped-for design.
+- Prefer task-oriented structure when users need to get something done.
+- Use precise terminology that matches the code and UI.
+- Include examples, prerequisites, and pitfalls when they materially improve clarity.
+- Keep docs aligned with adjacent pages and avoid fragmenting the source of truth.
+
+## Output expectations
+
+- Clear, accurate documentation update or new draft
+- Audience-appropriate level of technical detail
+- Explicit caveats, prerequisites, and compatibility notes when relevant
+
+## Quality checklist
+
+- Instructions are accurate against the current implementation.
+- The document helps someone complete a real task or understand a real concept.
+- Terms and examples are consistent with the product and codebase.
+- Important caveats are easy to find.
+
+## Handoff notes
+
+- Mention what was verified directly in code versus inferred from context.
+- Note any related docs that should be updated later to stay consistent.

skills/marketing/content-strategy-seo.md

@@ -0,0 +1,45 @@
+# Content Strategy and SEO
+
+## Purpose
+
+Create durable content plans and search-aligned messaging that compound over time instead of only supporting one launch moment.
+
+## When to use
+
+- Planning evergreen content around a product area
+- Improving discoverability for technical or product topics
+- Aligning content to audience intent and search behavior
+- Deciding which topics deserve durable written assets
+
+## Inputs to gather
+
+- Audience segments and their recurring questions
+- Product strengths, proof points, and topic authority
+- Existing content library and content gaps
+- Desired business outcome: discovery, education, conversion, or retention
+
+## How to work
+
+- Start from audience intent and recurring problems, not isolated keywords alone.
+- Organize content into durable themes that the product can support credibly.
+- Align titles, structure, and calls to action with user intent.
+- Avoid search-driven copy that weakens clarity or trust.
+- Prefer content that stays useful as the product evolves.
+
+## Output expectations
+
+- Content strategy, topic map, or SEO-aware draft direction
+- Prioritized content opportunities with rationale
+- Notes on how content connects to product positioning and documentation
+
+## Quality checklist
+
+- Recommendations reflect real audience needs.
+- Content ideas support durable value, not shallow traffic grabs.
+- Search alignment does not distort message clarity.
+- The strategy can inform multiple future assets.
+
+## Handoff notes
+
+- Note which assumptions are based on audience reasoning versus actual search data.
+- Pair with messaging/positioning and technical docs for strong, credible long-tail content.

skills/marketing/marketing-content.md

@@ -0,0 +1,45 @@
+# Marketing Content
+
+## Purpose
+
+Create external-facing content that explains, promotes, or launches product capabilities in a way that is accurate, audience-aware, and compelling.
+
+## When to use
+
+- Drafting launch posts, emails, feature pages, announcements, or social content
+- Turning product or engineering work into outward-facing communication
+- Adapting one core message into multiple channels
+- Creating content tied to a release or campaign
+
+## Inputs to gather
+
+- Audience, channel, and desired action
+- The actual product change or offer being communicated
+- Supporting proof points, examples, and differentiators
+- Voice, tone, and length constraints
+
+## How to work
+
+- Lead with why the audience should care.
+- Ground claims in the real product and its benefits.
+- Structure content so it is easy to scan and repurpose.
+- Tailor tone and density to the channel instead of reusing the same draft everywhere.
+- Keep technical explanations accurate while translating them into audience-relevant outcomes.
+
+## Output expectations
+
+- A polished draft for the requested channel
+- Supporting variations or headline options when useful
+- Clear call to action where appropriate
+
+## Quality checklist
+
+- The content is audience-centered, not feature-dump centered.
+- Claims are specific and defensible.
+- The narrative is easy to scan and follow.
+- The output matches the requested medium and length.
+
+## Handoff notes
+
+- State which audience and channel the draft targets.
+- Pair with messaging/positioning when the strategic framing is not yet settled.

skills/marketing/messaging-positioning.md

@@ -0,0 +1,45 @@
+# Messaging and Positioning
+
+## Purpose
+
+Clarify who the product or feature is for, what value it provides, why it matters now, and how it differs from alternatives.
+
+## When to use
+
+- Defining or refining product narrative
+- Preparing launches, landing pages, or feature announcements
+- Choosing how to frame a new capability for a target audience
+- Aligning product, UX, and marketing language around one story
+
+## Inputs to gather
+
+- Target audience and their pain points
+- Product capability, strengths, and evidence
+- Competitive or alternative solutions
+- Business goal of the messaging effort
+
+## How to work
+
+- Start with audience pain or desired outcome, then connect the product to that need.
+- Distinguish core value, supporting proof, and differentiators.
+- Avoid vague slogans unless they are backed by a concrete explanation.
+- Stress-test the message against realistic alternatives and skeptical readers.
+- Produce a tight core narrative that other copy can inherit.
+
+## Output expectations
+
+- Clear positioning statement or message framework
+- Defined audience, value proposition, and differentiators
+- Candidate headlines, pillars, or narrative directions when useful
+
+## Quality checklist
+
+- The message is specific about audience and value.
+- Differentiation is real, not generic category language.
+- Claims are supportable by the product.
+- The narrative can guide product copy and campaign content consistently.
+
+## Handoff notes
+
+- Note open questions about audience, market, or product maturity if they limit confidence.
+- Pair with product copy or marketing content to turn the narrative into shipped assets.

skills/marketing/product-copy.md

@@ -0,0 +1,45 @@
+# Product Copy
+
+## Purpose
+
+Write concise, user-facing product language that is clear, useful, on-brand, and matched to the immediate interface or conversion context.
+
+## When to use
+
+- Naming buttons, labels, helper text, empty states, and error messages
+- Tightening landing page or feature page copy
+- Improving clarity and persuasion in product-adjacent text
+- Rewriting awkward or confusing interface wording
+
+## Inputs to gather
+
+- Audience, goal, and context of the text
+- Current product voice and terminology
+- UI constraints such as length, hierarchy, and surrounding elements
+- Desired action or decision the copy should support
+
+## How to work
+
+- Optimize for clarity first, persuasion second, cleverness last.
+- Use the words users expect based on the product and task.
+- Match the level of confidence and urgency to the action being requested.
+- Keep text tight and scannable, especially in UI contexts.
+- Offer alternatives when tone or positioning is uncertain.
+
+## Output expectations
+
+- Final copy or strong candidate options
+- Brief rationale when choosing between meaningful directions
+- Notes on character, tone, or placement constraints when relevant
+
+## Quality checklist
+
+- Copy is clear on first read.
+- The wording fits the user's moment and intent.
+- Claims are credible and specific.
+- Text length is appropriate to the surface.
+
+## Handoff notes
+
+- Note if final selection depends on brand voice or product strategy not yet defined.
+- Pair with UX review for interface clarity and with messaging/positioning for strategic alignment.

skills/software/api-backend.md

@@ -0,0 +1,45 @@
+# API and Backend Work
+
+## Purpose
+
+Guide server-side, service, API, data, and integration changes with attention to contracts, compatibility, failure handling, and operational impact.
+
+## When to use
+
+- Modifying endpoints, handlers, services, jobs, or data flows
+- Adding or changing schemas, persistence, or integration behavior
+- Working on backend business logic or infrastructure-facing code
+- Investigating performance, reliability, or contract issues on the server side
+
+## Inputs to gather
+
+- API contracts, schema, storage models, and service boundaries
+- Existing validation, auth, error handling, and observability patterns
+- Compatibility constraints for clients, data, and deployments
+- Current tests and representative request or event flows
+
+## How to work
+
+- Trace the full request or job lifecycle before changing a boundary.
+- Preserve compatibility intentionally or document the break clearly.
+- Handle validation, authorization, error responses, and retries in line with existing system behavior.
+- Consider migration, rollout, and operational visibility when data or contracts change.
+- Add or update tests at the right layer for the change.
+
+## Output expectations
+
+- Working backend change with contract implications made explicit
+- Notes on schema, config, data, or rollout impact
+- Verification results covering the critical paths
+
+## Quality checklist
+
+- Inputs and outputs are validated appropriately.
+- Failure handling is explicit and consistent.
+- Compatibility and migration impact are understood.
+- Logging, metrics, or observability concerns are addressed when relevant.
+
+## Handoff notes
+
+- Call out any required coordination with frontend, data migration, configuration, or deployment steps.
+- Note backwards-incompatible changes clearly and early.

skills/software/architecture-system-design.md

@@ -0,0 +1,45 @@
+# Architecture and System Design
+
+## Purpose
+
+Shape meaningful technical direction so systems stay understandable, evolvable, and aligned with product needs over time.
+
+## When to use
+
+- Designing a major feature or subsystem
+- Changing service boundaries, module boundaries, or core data flow
+- Evaluating multiple implementation approaches with long-term consequences
+- Preparing work that will influence maintainability, scale, or team velocity
+
+## Inputs to gather
+
+- Current architecture, boundaries, and pain points
+- Product goals, scale expectations, and reliability constraints
+- Existing patterns, platform constraints, and team operating model
+- Compatibility, migration, and rollout concerns
+
+## How to work
+
+- Start from the user or system outcome, then identify the simplest architecture that supports it well.
+- Make tradeoffs explicit: complexity, performance, reliability, maintainability, and delivery speed.
+- Preserve useful existing boundaries unless there is a clear reason to change them.
+- Prefer designs that are easy to operate and easy for the team to understand.
+- Document why the chosen path is better than the main alternatives.
+
+## Output expectations
+
+- Clear recommended design or architecture direction
+- Explicit tradeoffs and constraints
+- Interfaces, boundaries, and rollout considerations that matter for implementation
+
+## Quality checklist
+
+- The design solves the actual problem, not a hypothetical future one.
+- Tradeoffs are named clearly enough to guide later decisions.
+- Complexity is justified by concrete needs.
+- Operational and migration consequences are not ignored.
+
+## Handoff notes
+
+- Pair with architecture decision records when the choice should be preserved for future contributors.
+- Call out which parts are decided versus intentionally deferred.

skills/software/code-review.md

@@ -0,0 +1,45 @@
+# Code Review
+
+## Purpose
+
+Review code with a bug-finding mindset that prioritizes correctness, regressions, risky assumptions, edge cases, and missing tests over style commentary.
+
+## When to use
+
+- Reviewing a pull request or patch
+- Auditing a risky change before merge
+- Evaluating whether a change is safe to ship
+- Checking for test and documentation gaps
+
+## Inputs to gather
+
+- The diff or changed files
+- Nearby code paths and contracts affected by the change
+- Existing tests, especially those intended to cover the modified behavior
+- Context on expected behavior, rollout risk, and compatibility requirements
+
+## How to work
+
+- Start with correctness, then move to regressions, then test gaps, then maintainability risks.
+- Trace changed code through call sites, error paths, and data flow rather than reading only the edited lines in isolation.
+- Focus comments on issues that materially affect behavior, safety, or maintainability.
+- Be explicit about severity and the concrete consequence of each issue.
+- Keep summary brief after listing the findings.
+
+## Output expectations
+
+- A prioritized list of findings with clear reasoning
+- Open questions or assumptions that affect confidence
+- Brief summary of overall risk after the findings
+
+## Quality checklist
+
+- Findings identify real behavior or verification risk, not cosmetic preferences.
+- Severity is proportional to user impact and likelihood.
+- Missing tests are called out where they reduce confidence materially.
+- If no issues are found, residual risk and coverage gaps are still noted.
+
+## Handoff notes
+
+- Include file references and tight line references when available.
+- Distinguish confirmed issues from lower-confidence concerns.

skills/software/database-migrations.md

@@ -0,0 +1,45 @@
+# Database Migrations and Data Evolution
+
+## Purpose
+
+Change schemas and data safely while protecting compatibility, correctness, rollout reliability, and recovery options.
+
+## When to use
+
+- Adding, removing, or changing database schema
+- Backfilling or transforming data
+- Introducing compatibility windows between old and new code
+- Planning rollout for data-sensitive changes
+
+## Inputs to gather
+
+- Current schema, access patterns, and data volume
+- Migration tooling and deployment model
+- Compatibility requirements across services, jobs, or clients
+- Rollback constraints and data recovery options
+
+## How to work
+
+- Prefer staged migrations when compatibility matters: expand, backfill, switch reads or writes, then contract.
+- Minimize lock risk, data loss risk, and long-running migration risk.
+- Consider how old and new code will coexist during rollout.
+- Define verification steps for schema state and critical data correctness.
+- Document irreversible steps and operator actions clearly.
+
+## Output expectations
+
+- Safe migration plan or implementation
+- Compatibility and rollout notes
+- Verification and rollback considerations
+
+## Quality checklist
+
+- The migration is safe for the repository's deployment model.
+- Data correctness is protected during and after rollout.
+- Backwards and forwards compatibility are considered when needed.
+- Irreversible or risky steps are made explicit.
+
+## Handoff notes
+
+- Call out sequencing requirements across application code, migrations, and background jobs.
+- Pair with release/change summary and technical docs when operators or teammates need a clear rollout path.

skills/software/dependency-lifecycle.md

@@ -0,0 +1,45 @@
+# Dependency Lifecycle Management
+
+## Purpose
+
+Keep dependencies healthy over time by balancing security, compatibility, maintainability, and upgrade cost.
+
+## When to use
+
+- Upgrading libraries, frameworks, runtimes, or tooling
+- Auditing dependency risk or staleness
+- Reducing upgrade backlog and ecosystem drift
+- Planning how to adopt breaking changes safely
+
+## Inputs to gather
+
+- Current dependency versions and their role in the system
+- Changelogs, upgrade guides, and breaking changes
+- Existing test coverage and high-risk integration points
+- Security, support-window, or maintenance concerns
+
+## How to work
+
+- Prefer focused upgrade batches that are easy to validate and revert.
+- Separate mechanical version bumps from behavior-changing adaptation when possible.
+- Read authoritative release notes before changing usage patterns.
+- Verify the highest-risk integration paths, not just installation success.
+- Capture follow-up work when a safe incremental upgrade leaves known deprecated patterns behind.
+
+## Output expectations
+
+- Upgrade plan or completed upgrade with adaptation notes
+- Risk summary for changed dependencies
+- Verification results and known remaining debt
+
+## Quality checklist
+
+- The upgrade reduces risk or maintenance burden meaningfully.
+- Breaking changes are understood before implementation.
+- Validation covers the most likely failure surfaces.
+- Residual deprecations or postponed steps are documented clearly.
+
+## Handoff notes
+
+- Note whether the work is a full upgrade, a safe intermediate step, or a reconnaissance pass.
+- Pair with test strategy and release/change summary when adoption affects developer workflow or runtime behavior.

skills/software/feature-implementation.md

@@ -0,0 +1,48 @@
+# Feature Implementation
+
+## Purpose
+
+Guide implementation of new behavior or meaningful changes to existing behavior with a bias toward working software, repository alignment, and practical verification.
+
+## When to use
+
+- Building a new feature
+- Expanding an existing workflow
+- Making a multi-file change that affects user or developer behavior
+- Turning a scoped request into implemented code
+
+## Inputs to gather
+
+- Relevant entrypoints, modules, and surrounding patterns
+- Existing interfaces, types, schema, and tests
+- User goal, success criteria, constraints, and impacted surfaces
+- Any repository instructions that override generic defaults
+
+## How to work
+
+- Inspect the codebase before editing and identify the smallest coherent change set.
+- Prefer existing patterns over introducing novel structure unless the current patterns are clearly limiting.
+- Implement end-to-end behavior, not just partial scaffolding, when feasible.
+- Keep logic changes close to the relevant module boundaries and avoid unrelated cleanup unless it materially helps the task.
+- Validate with targeted tests, builds, or manual checks appropriate to the repository.
+- Update docs, examples, or change notes when the feature alters usage or expectations.
+
+## Output expectations
+
+- A working implementation or a clearly explained blocker
+- Concise summary of what changed and why
+- Validation results and any gaps that remain
+- Notes on follow-up work only when it is genuinely important
+
+## Quality checklist
+
+- The change matches the stated goal and avoids unrelated churn.
+- Naming, structure, and style fit the existing codebase.
+- Errors, edge cases, and obvious failure paths are handled.
+- Verification is appropriate for the size and risk of the change.
+- User-facing or developer-facing behavior changes are documented when needed.
+
+## Handoff notes
+
+- Mention touched subsystems and any assumptions made because the repo did not answer them.
+- Call out migration or rollout concerns if the feature affects data, config, or compatibility.

skills/software/frontend-ui-implementation.md

@@ -0,0 +1,45 @@
+# Frontend UI Implementation
+
+## Purpose
+
+Guide interface implementation that balances correctness, usability, clarity, performance, and consistency with the existing product experience.
+
+## When to use
+
+- Building or updating pages, components, and interactions
+- Implementing client-side state or view logic
+- Adjusting layout, form flows, states, and visual feedback
+- Shipping UI changes tied to product behavior
+
+## Inputs to gather
+
+- Existing design system, component patterns, and styling conventions
+- User flow, content requirements, and responsive constraints
+- State, API, and error/loading behavior tied to the UI
+- Current tests, stories, screenshots, or acceptance criteria if available
+
+## How to work
+
+- Preserve the established visual language unless the task explicitly calls for a new direction.
+- Design for the full experience: loading, empty, error, success, and edge states.
+- Keep interaction logic understandable and avoid overengineering small UI behavior.
+- Use content, hierarchy, and spacing intentionally so the UI communicates clearly.
+- Validate on the most important screen sizes or states that the repository can reasonably support.
+
+## Output expectations
+
+- A functional UI change that is coherent visually and behaviorally
+- Clear notes on user-facing behavior and state handling
+- Verification appropriate to the stack, such as tests, stories, or manual checks
+
+## Quality checklist
+
+- The UI is understandable without hidden assumptions.
+- Important states are handled, not just the happy path.
+- Visual and code patterns fit the existing app.
+- Accessibility, responsiveness, and copy quality are considered.
+
+## Handoff notes
+
+- Mention any UX debts, unresolved visual questions, or browser/device gaps that remain.
+- Pair with UX review or product copy when usability or wording is central to the task.

skills/software/maintenance-technical-debt.md

@@ -0,0 +1,45 @@
+# Maintenance and Technical Debt Planning
+
+## Purpose
+
+Turn vague maintenance needs into a practical, sequenced plan that improves delivery speed, reliability, and future change safety over time.
+
+## When to use
+
+- The codebase has accumulated risky or slowing debt
+- A team needs to prioritize cleanup against feature work
+- Repeated friction suggests structural maintenance investment is overdue
+- You need to explain why maintenance work matters in product terms
+
+## Inputs to gather
+
+- Known pain points, repeated failures, and slow areas in delivery
+- Architectural hotspots, obsolete patterns, and fragile dependencies
+- Team constraints, roadmap pressure, and acceptable disruption
+- Evidence of cost: incidents, churn, slowed feature work, or support burden
+
+## How to work
+
+- Focus on debt that materially changes future delivery, reliability, or risk.
+- Group issues into themes rather than a flat list of annoyances.
+- Prioritize by impact, urgency, and dependency relationships.
+- Prefer incremental sequences that can ship safely between feature work.
+- Translate maintenance value into outcomes the team can defend.
+
+## Output expectations
+
+- Prioritized maintenance plan or backlog proposal
+- Clear rationale for what should happen now versus later
+- Sequencing guidance and expected payoff
+
+## Quality checklist
+
+- Recommendations are tied to real delivery or reliability pain.
+- Prioritization is explicit and defensible.
+- The plan is incremental enough to execute.
+- Work is framed in terms of reduced risk or increased velocity, not vague cleanliness.
+
+## Handoff notes
+
+- Note what evidence would strengthen or change the prioritization.
+- Pair with roadmap and opportunity prioritization when balancing debt against new initiatives.

skills/software/observability-operability.md

@@ -0,0 +1,45 @@
+# Observability and Operability
+
+## Purpose
+
+Make systems easier to understand, debug, and run by improving signals, diagnostics, and operational readiness around important behavior.
+
+## When to use
+
+- A system is hard to diagnose in production or staging
+- New functionality needs useful logs, metrics, traces, or alerts
+- Operational ownership is unclear during failures or rollout
+- Reliability work needs better visibility before deeper changes
+
+## Inputs to gather
+
+- Critical workflows, failure modes, and current diagnostic signals
+- Existing logging, metrics, tracing, dashboards, and alerts
+- Operator needs during rollout, incident response, and debugging
+- Noise constraints and performance or cost considerations
+
+## How to work
+
+- Instrument the questions a responder will need answered during failure.
+- Prefer signals tied to user-impacting behavior over vanity metrics.
+- Make logs structured and actionable when possible.
+- Add observability close to important boundaries and state transitions.
+- Keep signal quality high by avoiding low-value noise.
+
+## Output expectations
+
+- Improved observability or an operability plan for the target area
+- Clear explanation of what new signals reveal
+- Notes on alerting, dashboard, or rollout support when relevant
+
+## Quality checklist
+
+- Signals help detect and diagnose meaningful failures.
+- Instrumentation is focused and not excessively noisy.
+- Operational usage is considered, not just implementation convenience.
+- Added visibility maps to critical user or system outcomes.
+
+## Handoff notes
+
+- Mention what incidents or debugging tasks the new observability should make easier.
+- Pair with debugging workflow, incident response, or performance optimization when diagnosis is the main bottleneck.

skills/software/performance-optimization.md

@@ -0,0 +1,45 @@
+# Performance Optimization
+
+## Purpose
+
+Improve responsiveness and efficiency by focusing on the bottlenecks that matter most to users, systems, or operating cost.
+
+## When to use
+
+- Investigating slow pages, endpoints, jobs, or queries
+- Reducing memory, CPU, network, or rendering overhead
+- Preventing regressions in critical paths
+- Prioritizing optimization work with limited time
+
+## Inputs to gather
+
+- Performance symptoms, target metrics, and critical user or system paths
+- Existing measurements, profiles, logs, traces, or benchmarks
+- Current architecture and known hot spots
+- Acceptable tradeoffs in complexity, cost, and feature scope
+
+## How to work
+
+- Measure or inspect evidence before optimizing.
+- Focus on the dominant bottleneck rather than broad cleanup.
+- Prefer changes that improve the critical path without making the system harder to maintain.
+- Re-measure after changes when possible.
+- Capture the conditions under which the optimization matters so future work does not cargo-cult it.
+
+## Output expectations
+
+- Bottleneck diagnosis and recommended or implemented improvement
+- Before-and-after evidence when available
+- Notes on tradeoffs, limits, and remaining hot spots
+
+## Quality checklist
+
+- Optimization targets a real bottleneck.
+- Claimed gains are grounded in evidence, not assumption alone.
+- Complexity added by the optimization is justified.
+- Regression risk is considered for correctness and maintainability.
+
+## Handoff notes
+
+- Note whether the result is measured, estimated, or hypothesis-driven.
+- Pair with observability and operability when instrumentation is weak.

skills/software/refactoring.md

@@ -0,0 +1,45 @@
+# Refactoring
+
+## Purpose
+
+Improve code structure, readability, maintainability, or modularity without intentionally changing externally observable behavior.
+
+## When to use
+
+- Simplifying complex logic
+- Extracting clearer abstractions
+- Reducing duplication or coupling
+- Preparing code for future work while preserving behavior
+
+## Inputs to gather
+
+- Current behavior and tests that define expected outcomes
+- Structural pain points in the relevant modules
+- Constraints around public APIs, compatibility, or performance
+- Existing patterns for abstraction and module boundaries
+
+## How to work
+
+- Preserve behavior intentionally and define what must remain unchanged before editing.
+- Favor small, reviewable moves over sweeping rewrites unless the code is already unsafe to work in incrementally.
+- Keep interface changes minimal and justified.
+- Add or strengthen tests when behavior preservation is important and current coverage is weak.
+- Separate cleanup that supports the refactor from unrelated aesthetic changes.
+
+## Output expectations
+
+- Cleaner code with behavior preserved
+- Clear explanation of the structural improvement
+- Verification evidence that the refactor did not break expected behavior
+
+## Quality checklist
+
+- Intended behavior is unchanged unless explicitly documented otherwise.
+- The resulting structure is easier to understand or extend.
+- Interface changes are minimal, justified, and documented.
+- Added complexity is avoided unless it buys meaningful maintainability.
+
+## Handoff notes
+
+- Call out any areas where behavior preservation is inferred rather than strongly verified.
+- Note future cleanup opportunities only if they naturally follow from the refactor.

skills/software/release-change-summary.md

@@ -0,0 +1,45 @@
+# Release and Change Summary
+
+## Purpose
+
+Explain shipped or proposed changes clearly for developers, operators, collaborators, or end users, with emphasis on what changed, why it matters, and what action is required.
+
+## When to use
+
+- Writing release notes or changelog entries
+- Summarizing completed engineering work
+- Explaining migration or rollout impact
+- Turning technical changes into clear stakeholder communication
+
+## Inputs to gather
+
+- The actual code or product changes
+- Intended audience and their level of technical depth
+- Any rollout, migration, compatibility, or operational considerations
+- Linked docs, issues, or feature context that explains why the change exists
+
+## How to work
+
+- Lead with the user-meaningful change, not internal implementation trivia.
+- Group related changes into a few clear themes rather than a raw diff dump.
+- Call out required actions, migrations, or risks explicitly.
+- Tailor the level of detail to the audience.
+- Keep the summary accurate to the implementation that actually landed.
+
+## Output expectations
+
+- Clear release notes, summary, or change communication draft
+- Audience-appropriate explanation of impact and required action
+- Explicit mention of follow-up items only when relevant
+
+## Quality checklist
+
+- The summary matches the real change, not the original intent alone.
+- Important caveats, migrations, and compatibility notes are visible.
+- Wording is concise and easy to scan.
+- Audience knowledge level is respected.
+
+## Handoff notes
+
+- Say who the summary is for and what medium it targets if that is not obvious.
+- Pair with technical docs or marketing skills when the output needs deeper explanation or stronger positioning.

skills/software/repo-exploration.md

@@ -0,0 +1,44 @@
+# Repository Exploration
+
+## Purpose
+
+Rapidly build accurate context before implementation, debugging, or planning by identifying the right files, flows, conventions, and constraints in the repository.
+
+## When to use
+
+- Starting in an unfamiliar repository
+- Locating the right implementation area for a request
+- Understanding current architecture before proposing changes
+- Reducing ambiguity in a vague task
+
+## Inputs to gather
+
+- Repository layout, entrypoints, and key modules
+- Build, test, and dependency configuration
+- Existing patterns for similar features or workflows
+- Any local instructions, docs, or conventions already in the repo
+
+## How to work
+
+- Start broad, then narrow quickly to the files and flows relevant to the task.
+- Favor authoritative sources in the repo such as configs, types, interfaces, docs, and existing implementations.
+- Identify where decisions are already made by the codebase so you do not reinvent them.
+- Summarize findings in terms of how they affect the next action.
+- Stop exploring once the path to execution is clear enough.
+
+## Output expectations
+
+- Concise map of the relevant code paths and conventions
+- Recommended starting points for changes or further investigation
+- Key unknowns that still require validation
+
+## Quality checklist
+
+- Exploration answers practical implementation questions rather than producing generic architecture prose.
+- Findings are tied to concrete files, modules, or workflows.
+- Enough context is gathered to act confidently without over-reading the entire repo.
+
+## Handoff notes
+
+- Mention the most relevant files, commands, and repo conventions discovered.
+- Flag ambiguous areas where multiple plausible implementation paths exist.

skills/software/security-review-hardening.md

@@ -0,0 +1,45 @@
+# Security Review and Hardening
+
+## Purpose
+
+Reduce avoidable security risk by reviewing trust boundaries, sensitive data handling, exposure paths, and abuse opportunities in the relevant system area.
+
+## When to use
+
+- Shipping authentication, authorization, input handling, or sensitive workflows
+- Reviewing an externally exposed feature or API
+- Auditing risky changes for common security failures
+- Hardening an existing system area with known gaps
+
+## Inputs to gather
+
+- Trust boundaries, user roles, and entry points
+- Sensitive data flows, secrets, tokens, or privileged operations
+- Existing auth, validation, logging, and rate limiting patterns
+- Relevant compliance or threat concerns if known
+
+## How to work
+
+- Start with who can do what, from where, and with which inputs.
+- Check validation, authorization, data exposure, secret handling, and abuse resistance.
+- Prefer concrete mitigations over vague warnings.
+- Align with existing security controls unless they are clearly insufficient.
+- Call out unverified areas when the environment or tooling limits confidence.
+
+## Output expectations
+
+- Concrete risks found or a scoped hardening plan
+- Recommended mitigations tied to the actual threat surface
+- Clear statement of confidence and any blind spots
+
+## Quality checklist
+
+- Review covers the real trust boundaries and attack surface.
+- Findings describe exploit consequence, not just theoretical concern.
+- Mitigations are practical for the system and team.
+- Residual risk is visible where hardening is incomplete.
+
+## Handoff notes
+
+- Separate must-fix risks from defense-in-depth improvements.
+- Pair with code review, API/backend work, and observability when the issue spans implementation and detection.

skills/software/test-strategy.md

@@ -0,0 +1,45 @@
+# Test Strategy
+
+## Purpose
+
+Choose and evaluate the right level of verification so changes are covered proportionally to their risk, behavior, and maintenance cost.
+
+## When to use
+
+- Adding or updating tests for a feature or bug fix
+- Deciding what verification is necessary before shipping
+- Auditing coverage gaps in existing code
+- Designing regression protection for risky areas
+
+## Inputs to gather
+
+- The behavior being changed or protected
+- Current test layout, tooling, and conventions
+- Known failure modes, regressions, or edge cases
+- Constraints on test speed, environment, and confidence needs
+
+## How to work
+
+- Match test level to risk: unit for logic, integration for boundaries, end-to-end for critical workflows.
+- Prefer the smallest test that meaningfully protects the behavior.
+- Cover success paths, likely failure paths, and regressions suggested by the change.
+- Reuse existing fixtures and patterns where possible.
+- If tests are not feasible, define alternate validation steps and explain the gap.
+
+## Output expectations
+
+- Specific recommended or implemented tests
+- Clear rationale for test level and scope
+- Any remaining uncovered risks or follow-up test ideas
+
+## Quality checklist
+
+- Tests target behavior, not implementation trivia.
+- Coverage includes the change's highest-risk paths.
+- Test design fits repository conventions and runtime cost expectations.
+- Non-tested areas are called out explicitly when important.
+
+## Handoff notes
+
+- Note flaky, expensive, or environment-dependent checks separately from fast local confidence checks.
+- Mention whether the test plan is implemented, recommended, or partially blocked.

skills/ui-ux/accessibility-review.md

@@ -0,0 +1,45 @@
+# Accessibility Review
+
+## Purpose
+
+Improve inclusive usability by checking whether interfaces are operable, understandable, and robust for people using different devices, input methods, and assistive technologies.
+
+## When to use
+
+- Reviewing or implementing user-facing UI
+- Checking forms, dialogs, navigation, or interactive states
+- Improving keyboard support, semantics, contrast, or feedback
+- Raising the quality bar for long-lived interface patterns
+
+## Inputs to gather
+
+- Relevant screens, components, and interaction flows
+- Existing design system, semantic patterns, and accessibility goals
+- Keyboard, screen reader, focus, contrast, and motion considerations
+- Known constraints in the stack or component library
+
+## How to work
+
+- Check the main user path with keyboard and semantics in mind first.
+- Review labels, focus order, state announcements, contrast, and error clarity.
+- Prioritize issues that block task completion or create major confusion.
+- Recommend changes that fit the current implementation model and team capacity.
+- Treat accessibility as product quality, not a final polish pass.
+
+## Output expectations
+
+- Clear accessibility findings or implementation guidance
+- Prioritized fixes by impact on usability and inclusion
+- Notes on what was inspected directly versus inferred
+
+## Quality checklist
+
+- Findings focus on real interaction barriers.
+- Recommendations are specific enough to implement.
+- The review covers both semantics and user experience.
+- High-impact accessibility gaps are surfaced early.
+
+## Handoff notes
+
+- Mention whether checks were code-based, visual, or manually reasoned.
+- Pair with frontend UI implementation and design system consistency when shipping durable fixes.

skills/ui-ux/design-system-consistency.md

@@ -0,0 +1,45 @@
+# Design System and UI Consistency
+
+## Purpose
+
+Promote reusable, scalable UI patterns so the interface stays coherent as the product grows.
+
+## When to use
+
+- A UI area is drifting from existing patterns
+- Reusable components or patterns should replace one-off implementations
+- A feature adds new patterns that may affect future screens
+- You want to improve consistency without a full redesign
+
+## Inputs to gather
+
+- Existing components, tokens, layout patterns, and style conventions
+- The new or changed UI requirements
+- Current inconsistencies, duplication, or local hacks
+- Constraints from the stack, theme system, or design resources
+
+## How to work
+
+- Reuse existing components and conventions before inventing new ones.
+- Introduce new patterns only when the current system cannot express the need cleanly.
+- Optimize for maintainability and consistency, not just a one-screen outcome.
+- Keep component APIs and styling patterns understandable.
+- Document new reusable patterns when they materially expand the design system.
+
+## Output expectations
+
+- More consistent UI implementation or a clear plan for pattern consolidation
+- Notes on reused versus newly introduced patterns
+- Guidance on where the system should expand carefully
+
+## Quality checklist
+
+- The UI becomes more coherent, not more fragmented.
+- Reuse is meaningful and does not force a poor fit.
+- New abstractions are justified by repeated or durable need.
+- The solution helps future features move faster.
+
+## Handoff notes
+
+- Note whether the work is local cleanup, reusable component work, or system-level direction.
+- Pair with UX review and frontend implementation when consistency changes affect behavior and clarity.

skills/ui-ux/ux-review.md

@@ -0,0 +1,45 @@
+# UX Review
+
+## Purpose
+
+Evaluate an interface or flow for clarity, usability, friction, trust, and task completion quality, then turn those observations into actionable improvements.
+
+## When to use
+
+- Reviewing a screen or flow before or after implementation
+- Looking for usability issues in forms, navigation, settings, or onboarding
+- Improving hierarchy, copy clarity, state handling, or feedback
+- Assessing whether an interface supports the intended user goal well
+
+## Inputs to gather
+
+- Screens, flows, components, or descriptions of the experience
+- Target user goal and success criteria
+- Existing design system or product patterns
+- Constraints such as device, context, accessibility, or content requirements
+
+## How to work
+
+- Review from the user's task perspective rather than from the component tree outward.
+- Check whether the next action is obvious at each step.
+- Evaluate hierarchy, wording, spacing, feedback, and state transitions together.
+- Prioritize issues by how much they block comprehension, confidence, or completion.
+- Suggest improvements that fit the current product language unless redesign is requested.
+
+## Output expectations
+
+- Clear list of UX issues or strengths
+- Prioritized recommendations with rationale
+- Notes on where UI changes, copy changes, or research would help most
+
+## Quality checklist
+
+- Feedback is tied to user outcomes, not vague aesthetic preference.
+- Important states such as empty, loading, error, and success are considered.
+- Recommendations are specific enough to act on.
+- Suggestions fit the product's current level of complexity and style.
+
+## Handoff notes
+
+- Distinguish between usability issues, visual polish issues, and copy issues.
+- Pair with frontend implementation or product copy when turning review into shipped changes.

src/client/admin/main.ts

@@ -0,0 +1,149 @@
+import '../style.css'
+
+// ---- Toast utility -------------------------------------------------------
+
+function showToast(msg: string, durationMs = 2500) {
+  const toast   = document.getElementById('toast')
+  const toastMsg = document.getElementById('toast-msg')
+  if (!toast || !toastMsg) return
+  toastMsg.textContent = msg
+  toast.classList.remove('opacity-0', 'translate-y-2', 'pointer-events-none')
+  toast.classList.add('opacity-100', 'translate-y-0')
+  setTimeout(() => {
+    toast.classList.add('opacity-0', 'translate-y-2', 'pointer-events-none')
+    toast.classList.remove('opacity-100', 'translate-y-0')
+  }, durationMs)
+}
+
+// ---- Copy-link buttons ---------------------------------------------------
+
+document.querySelectorAll<HTMLButtonElement>('.copy-link-btn').forEach(btn => {
+  btn.addEventListener('click', async () => {
+    const url = btn.dataset.url ?? ''
+    try {
+      await navigator.clipboard.writeText(url)
+      showToast('Link copied to clipboard')
+    } catch {
+      // Fallback for non-secure contexts
+      const ta = document.createElement('textarea')
+      ta.value = url
+      ta.style.position = 'fixed'
+      ta.style.opacity = '0'
+      document.body.appendChild(ta)
+      ta.select()
+      document.execCommand('copy')
+      document.body.removeChild(ta)
+      showToast('Link copied to clipboard')
+    }
+  })
+})
+
+// ---- Visibility toggles --------------------------------------------------
+
+document.querySelectorAll<HTMLButtonElement>('.visibility-toggle').forEach(btn => {
+  btn.addEventListener('click', async () => {
+    const id = btn.dataset.modelId
+    if (!id) return
+    try {
+      const res  = await fetch(`/api/admin/models/${id}/visibility`, { method: 'POST' })
+      const data = await res.json() as { is_public: 0 | 1 }
+
+      const isPublic = data.is_public === 1
+      const dot = btn.querySelector('span')
+
+      btn.dataset.isPublic = String(data.is_public)
+      btn.className = btn.className.replace(
+        /bg-(green|gray)-\S+|border-(green|gray)-\S+|text-(green|gray)-\S+/g, ''
+      )
+      btn.classList.add(
+        ...(isPublic
+          ? ['bg-green-500/10', 'border-green-500/30', 'text-green-400']
+          : ['bg-gray-700/50', 'border-gray-700', 'text-gray-500'])
+      )
+      if (dot) {
+        dot.className = `w-1.5 h-1.5 rounded-full ${isPublic ? 'bg-green-400' : 'bg-gray-500'}`
+      }
+      btn.childNodes.forEach(node => {
+        if (node.nodeType === Node.TEXT_NODE) {
+          node.textContent = ` ${isPublic ? 'Public' : 'Private'}`
+        }
+      })
+      showToast(isPublic ? 'Model set to public' : 'Model set to private')
+    } catch {
+      showToast('Failed to update visibility')
+    }
+  })
+})
+
+// ---- File drop zone ------------------------------------------------------
+
+const dropZone = document.getElementById('drop-zone')
+const fileInput = document.getElementById('model_file') as HTMLInputElement | null
+const fileNameDisplay = document.getElementById('file-name')
+
+if (dropZone && fileInput) {
+  dropZone.addEventListener('dragover', e => {
+    e.preventDefault()
+    dropZone.classList.add('border-accent')
+  })
+  dropZone.addEventListener('dragleave', () => {
+    dropZone.classList.remove('border-accent')
+  })
+  dropZone.addEventListener('drop', e => {
+    e.preventDefault()
+    dropZone.classList.remove('border-accent')
+    const files = e.dataTransfer?.files
+    if (files?.length) {
+      // Transfer to the real file input via DataTransfer
+      const dt = new DataTransfer()
+      dt.items.add(files[0])
+      fileInput.files = dt.files
+      showFileName(files[0].name)
+
+      // Auto-fill name field if empty
+      const nameInput = document.getElementById('name') as HTMLInputElement | null
+      if (nameInput && !nameInput.value) {
+        nameInput.value = files[0].name.replace(/\.(step|stp|stl)$/i, '')
+      }
+    }
+  })
+
+  fileInput.addEventListener('change', () => {
+    if (fileInput.files?.[0]) showFileName(fileInput.files[0].name)
+  })
+
+  function showFileName(name: string) {
+    if (fileNameDisplay) {
+      fileNameDisplay.textContent = `Selected: ${name}`
+      fileNameDisplay.classList.remove('hidden')
+    }
+  }
+}
+
+// ---- Inline category edit toggle ----------------------------------------
+
+document.querySelectorAll<HTMLElement>('.edit-btn').forEach(btn => {
+  btn.addEventListener('click', () => {
+    const row        = btn.closest('[class*="hover:bg"]') as HTMLElement
+    const form       = row?.querySelector<HTMLElement>('.edit-form')
+    const actionBtns = row?.querySelector<HTMLElement>('.action-buttons')
+    if (form && actionBtns) {
+      form.classList.remove('hidden')
+      form.classList.add('flex')
+      actionBtns.classList.add('hidden')
+    }
+  })
+})
+
+document.querySelectorAll<HTMLElement>('.cancel-edit').forEach(btn => {
+  btn.addEventListener('click', () => {
+    const row        = btn.closest('[class*="hover:bg"]') as HTMLElement
+    const form       = row?.querySelector<HTMLElement>('.edit-form')
+    const actionBtns = row?.querySelector<HTMLElement>('.action-buttons')
+    if (form && actionBtns) {
+      form.classList.add('hidden')
+      form.classList.remove('flex')
+      actionBtns.classList.remove('hidden')
+    }
+  })
+})

src/client/style.css

@@ -0,0 +1,31 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * { box-sizing: border-box; }
+
+  :root {
+    --accent: #3b82f6;
+  }
+
+  html {
+    font-family: 'Inter', system-ui, sans-serif;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  /* Scrollbar styling for dark mode */
+  ::-webkit-scrollbar { width: 6px; height: 6px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: #374151; border-radius: 3px; }
+  ::-webkit-scrollbar-thumb:hover { background: #4b5563; }
+}
+
+@layer utilities {
+  .line-clamp-2 {
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+}

src/client/viewer/main.ts

@@ -0,0 +1,379 @@
+import '../style.css'
+import * as THREE from 'three'
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
+import { STLLoader } from 'three/addons/loaders/STLLoader.js'
+import type { GeometryFile } from '../../server/services/stepConverter'
+
+// ---- Data injected by viewer.ejs -----------------------------------------
+
+declare const __STEPVIEW__: {
+  modelId:     number
+  fileType:    'step' | 'stp' | 'stl'
+  shareUrl:    string
+  hasPdfs:     boolean
+  hasGeometry: boolean   // pre-processed geometry JSON exists (STEP/STP only)
+}
+
+// ---- Scene state ---------------------------------------------------------
+
+let renderer: THREE.WebGLRenderer
+let scene:    THREE.Scene
+let camera:   THREE.PerspectiveCamera
+let controls: OrbitControls
+
+// ---- UI helpers ----------------------------------------------------------
+
+function setLoading(msg: string) {
+  const el = document.getElementById('loading-msg')
+  if (el) el.textContent = msg
+}
+
+function hideLoading() {
+  const overlay = document.getElementById('loading-overlay') as HTMLElement
+  overlay.style.opacity = '0'
+  setTimeout(() => { overlay.style.display = 'none' }, 300)
+}
+
+function showError(msg: string) {
+  document.getElementById('loading-overlay')!.style.display = 'none'
+  const overlay = document.getElementById('error-overlay')!
+  overlay.classList.remove('hidden')
+  overlay.classList.add('flex')
+  const msgEl = document.getElementById('error-msg')
+  if (msgEl) msgEl.textContent = msg
+}
+
+function showToast(msg: string, duration = 2200) {
+  const toast    = document.getElementById('toast')!
+  const toastMsg = document.getElementById('toast-msg')!
+  toastMsg.textContent = msg
+  toast.classList.remove('opacity-0', 'pointer-events-none')
+  toast.classList.add('opacity-100')
+  setTimeout(() => {
+    toast.classList.add('opacity-0', 'pointer-events-none')
+    toast.classList.remove('opacity-100')
+  }, duration)
+}
+
+// ---- Scene setup ---------------------------------------------------------
+
+function buildScene(canvas: HTMLCanvasElement) {
+  renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false })
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
+  renderer.setSize(window.innerWidth, window.innerHeight)
+  renderer.setClearColor(0x0a0a0f, 1)
+  renderer.shadowMap.enabled = true
+  renderer.shadowMap.type    = THREE.PCFSoftShadowMap
+  renderer.outputColorSpace   = THREE.SRGBColorSpace
+  renderer.toneMapping        = THREE.ACESFilmicToneMapping
+  renderer.toneMappingExposure = 1.1
+
+  scene = new THREE.Scene()
+
+  // Subtle environment fog
+  scene.fog = new THREE.FogExp2(0x0a0a0f, 0.0008)
+
+  camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.001, 10000)
+  camera.position.set(5, 3, 8)
+
+  // Lighting
+  const ambient = new THREE.AmbientLight(0xffffff, 0.5)
+  scene.add(ambient)
+
+  const key = new THREE.DirectionalLight(0xffffff, 2.0)
+  key.position.set(10, 20, 10)
+  key.castShadow = true
+  key.shadow.mapSize.set(2048, 2048)
+  key.shadow.camera.near = 0.1
+  key.shadow.camera.far  = 500
+  scene.add(key)
+
+  const fill = new THREE.DirectionalLight(0x8899cc, 0.4)
+  fill.position.set(-10, 5, -10)
+  scene.add(fill)
+
+  const rim = new THREE.DirectionalLight(0xffffff, 0.2)
+  rim.position.set(0, -5, -10)
+  scene.add(rim)
+
+  controls = new OrbitControls(camera, renderer.domElement)
+  controls.enableDamping  = true
+  controls.dampingFactor  = 0.06
+  controls.minDistance    = 0.001
+  controls.maxDistance    = 5000
+  controls.panSpeed       = 0.8
+  controls.rotateSpeed    = 0.6
+  controls.zoomSpeed      = 1.2
+
+  window.addEventListener('resize', () => {
+    camera.aspect = window.innerWidth / window.innerHeight
+    camera.updateProjectionMatrix()
+    renderer.setSize(window.innerWidth, window.innerHeight)
+  })
+}
+
+// ---- Render loop ---------------------------------------------------------
+
+function startRenderLoop() {
+  const clock = new THREE.Clock()
+  function tick() {
+    requestAnimationFrame(tick)
+    controls.update()
+    renderer.render(scene, camera)
+    void clock
+  }
+  tick()
+}
+
+// ---- Camera fit ----------------------------------------------------------
+
+function fitCamera(object: THREE.Object3D) {
+  const box    = new THREE.Box3().setFromObject(object)
+  const size   = box.getSize(new THREE.Vector3())
+  const center = box.getCenter(new THREE.Vector3())
+  const maxDim = Math.max(size.x, size.y, size.z)
+
+  if (maxDim === 0) return
+
+  const fovRad = camera.fov * (Math.PI / 180)
+  const dist   = (maxDim / (2 * Math.tan(fovRad / 2))) * 1.6
+
+  camera.near = maxDim * 0.0005
+  camera.far  = maxDim * 200
+  camera.updateProjectionMatrix()
+
+  camera.position.set(
+    center.x + dist * 0.55,
+    center.y + dist * 0.35,
+    center.z + dist,
+  )
+  camera.lookAt(center)
+  controls.target.copy(center)
+  controls.update()
+}
+
+// ---- Ground grid ---------------------------------------------------------
+
+function addGrid(object: THREE.Object3D) {
+  const box    = new THREE.Box3().setFromObject(object)
+  const size   = box.getSize(new THREE.Vector3())
+  const center = box.getCenter(new THREE.Vector3())
+  const maxDim = Math.max(size.x, size.z) * 3
+
+  const grid = new THREE.GridHelper(maxDim, 20, 0x1a1a2a, 0x1a1a2a)
+  grid.position.set(center.x, box.min.y - 0.001, center.z)
+  scene.add(grid)
+}
+
+// ---- Material factory ----------------------------------------------------
+
+function makeMaterial(color: [number, number, number] | null): THREE.MeshStandardMaterial {
+  const c = color
+    ? new THREE.Color(color[0], color[1], color[2])
+    : new THREE.Color(0x8fa3b8)
+  return new THREE.MeshStandardMaterial({
+    color:     c,
+    roughness: 0.45,
+    metalness: 0.25,
+    side:      THREE.DoubleSide,
+  })
+}
+
+// ---- STEP/STP loader (geometry JSON, pre-processed server-side) ----------
+
+async function loadStepGeometry(): Promise<void> {
+  setLoading('Fetching geometry…')
+  const res = await fetch(`/files/geometry/${__STEPVIEW__.modelId}`)
+
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({})) as { processing?: boolean }
+    if (body.processing) {
+      throw new Error('This model is still being processed. Please try again in a moment.')
+    }
+    throw new Error(`Could not load geometry (HTTP ${res.status})`)
+  }
+
+  setLoading('Building 3D scene…')
+  const data = await res.json() as GeometryFile
+
+  if (!data.meshes || data.meshes.length === 0) {
+    throw new Error('Geometry file contains no meshes.')
+  }
+
+  const group = new THREE.Group()
+
+  for (const mesh of data.meshes) {
+    const geo = new THREE.BufferGeometry()
+    geo.setAttribute('position', new THREE.Float32BufferAttribute(mesh.positions, 3))
+
+    if (mesh.normals && mesh.normals.length > 0) {
+      geo.setAttribute('normal', new THREE.Float32BufferAttribute(mesh.normals, 3))
+    }
+
+    if (mesh.indices && mesh.indices.length > 0) {
+      geo.setIndex(new THREE.Uint32BufferAttribute(mesh.indices, 1))
+    }
+
+    if (!mesh.normals || mesh.normals.length === 0) {
+      geo.computeVertexNormals()
+    }
+
+    group.add(new THREE.Mesh(geo, makeMaterial(mesh.color)))
+  }
+
+  scene.add(group)
+  fitCamera(group)
+  addGrid(group)
+}
+
+// ---- STL loader (client-side, Three.js built-in) -------------------------
+
+async function loadStl(): Promise<void> {
+  setLoading('Fetching STL file…')
+  const loader = new STLLoader()
+
+  const geometry = await new Promise<THREE.BufferGeometry>((resolve, reject) => {
+    loader.load(
+      `/files/model/${__STEPVIEW__.modelId}`,
+      resolve,
+      (xhr) => {
+        if (xhr.total) {
+          const pct = Math.round((xhr.loaded / xhr.total) * 100)
+          setLoading(`Downloading STL… ${pct}%`)
+        }
+      },
+      reject,
+    )
+  })
+
+  setLoading('Building 3D scene…')
+  geometry.computeVertexNormals()
+
+  // Center geometry at origin
+  geometry.computeBoundingBox()
+  const center = new THREE.Vector3()
+  geometry.boundingBox!.getCenter(center)
+  geometry.translate(-center.x, -center.y, -center.z)
+
+  const mesh = new THREE.Mesh(geometry, makeMaterial(null))
+  mesh.castShadow    = true
+  mesh.receiveShadow = true
+  scene.add(mesh)
+  fitCamera(mesh)
+  addGrid(mesh)
+}
+
+// ---- Viewer toolbar ------------------------------------------------------
+
+function wireToolbar() {
+  // Copy-link
+  const copyBtn = document.getElementById('copy-link-btn') as HTMLButtonElement | null
+  if (copyBtn) {
+    copyBtn.addEventListener('click', async () => {
+      try {
+        await navigator.clipboard.writeText(__STEPVIEW__.shareUrl)
+      } catch {
+        const ta = Object.assign(document.createElement('textarea'), {
+          value: __STEPVIEW__.shareUrl,
+          style: 'position:fixed;opacity:0',
+        })
+        document.body.appendChild(ta)
+        ta.select()
+        document.execCommand('copy')
+        document.body.removeChild(ta)
+      }
+      const orig = copyBtn.innerHTML
+      copyBtn.textContent = '✓ Copied!'
+      setTimeout(() => { copyBtn.innerHTML = orig }, 2000)
+    })
+  }
+
+  // Reset camera
+  const resetBtn = document.getElementById('reset-camera-btn')
+  if (resetBtn) {
+    resetBtn.addEventListener('click', () => {
+      // Re-fit camera to scene objects (exclude grid)
+      const objects = scene.children.filter(c => !(c instanceof THREE.GridHelper))
+      const group   = new THREE.Group()
+      objects.forEach(o => group.add(o.clone()))
+      if (group.children.length) fitCamera(group)
+    })
+  }
+
+  // Wireframe toggle
+  let wireframe = false
+  const wireBtn = document.getElementById('wireframe-btn')
+  if (wireBtn) {
+    wireBtn.addEventListener('click', () => {
+      wireframe = !wireframe
+      scene.traverse(obj => {
+        if (obj instanceof THREE.Mesh && obj.material instanceof THREE.MeshStandardMaterial) {
+          obj.material.wireframe = wireframe
+        }
+      })
+      wireBtn.classList.toggle('text-accent', wireframe)
+    })
+  }
+
+  // PDF panel
+  const pdfToggle = document.getElementById('pdf-toggle-btn')
+  const pdfPanel  = document.getElementById('pdf-panel')
+  const pdfClose  = document.getElementById('pdf-close-btn')
+
+  if (pdfToggle && pdfPanel) {
+    pdfToggle.addEventListener('click', () => pdfPanel.classList.toggle('closed'))
+  }
+  if (pdfClose && pdfPanel) {
+    pdfClose.addEventListener('click', () => pdfPanel.classList.add('closed'))
+  }
+
+  // PDF tabs
+  document.querySelectorAll<HTMLButtonElement>('.pdf-tab').forEach(tab => {
+    tab.addEventListener('click', () => {
+      const idx = tab.dataset.tab
+      document.querySelectorAll('.pdf-tab').forEach(t => {
+        t.classList.remove('border-accent', 'text-white')
+        t.classList.add('border-transparent', 'text-gray-500')
+      })
+      tab.classList.add('border-accent', 'text-white')
+      tab.classList.remove('border-transparent', 'text-gray-500')
+      document.querySelectorAll<HTMLElement>('.pdf-frame').forEach(f => {
+        f.classList.toggle('hidden', f.dataset.frame !== idx)
+      })
+    })
+  })
+}
+
+// ---- Boot ----------------------------------------------------------------
+
+async function boot() {
+  const canvas = document.getElementById('viewer-canvas') as HTMLCanvasElement
+
+  try {
+    buildScene(canvas)
+    startRenderLoop()
+    wireToolbar()
+
+    if (__STEPVIEW__.fileType === 'stl') {
+      await loadStl()
+    } else {
+      // STEP / STP
+      if (!__STEPVIEW__.hasGeometry) {
+        throw new Error(
+          'This model has not finished processing yet. ' +
+          'Please check back shortly or contact your administrator.'
+        )
+      }
+      await loadStepGeometry()
+    }
+
+    hideLoading()
+  } catch (err) {
+    console.error('[StepView]', err)
+    showError(err instanceof Error ? err.message : String(err))
+  }
+}
+
+boot()
+
+export {}

src/server/app.ts

@@ -0,0 +1,100 @@
+import 'dotenv/config'
+import express from 'express'
+import compression from 'compression'
+import session from 'express-session'
+import path from 'path'
+import fs from 'fs'
+
+// Initialize DB (runs schema + seeds) before anything else
+import './db/index'
+
+import { injectBrand } from './middleware/injectBrand'
+import { warmUpOcct } from './services/stepConverter'
+import authRoutes           from './routes/auth'
+import adminModelRoutes     from './routes/adminModels'
+import adminCategoryRoutes  from './routes/adminCategories'
+import adminSettingsRoutes  from './routes/adminSettings'
+import viewerRoutes         from './routes/viewer'
+import fileRoutes           from './routes/files'
+
+const app  = express()
+const PORT = parseInt(process.env.PORT ?? '3000', 10)
+
+// Ensure upload dirs exist
+const UPLOADS_DIR = process.env.UPLOADS_DIR ?? path.join(process.cwd(), 'uploads')
+for (const sub of ['models', 'pdfs', 'thumbnails', 'brand']) {
+  fs.mkdirSync(path.join(UPLOADS_DIR, sub), { recursive: true })
+}
+
+// Warm up WASM in background so the first STEP upload is fast
+warmUpOcct()
+
+// ---- View engine ----------------------------------------------------------
+app.set('view engine', 'ejs')
+app.set('views', path.join(process.cwd(), 'views'))
+
+// ---- Compression (gzip geometry JSON, etc.) ------------------------------
+app.use(compression())
+
+// ---- Static files --------------------------------------------------------
+app.use(express.static(path.join(process.cwd(), 'public')))
+
+// ---- Body parsing --------------------------------------------------------
+app.use(express.urlencoded({ extended: true }))
+app.use(express.json())
+
+// ---- Sessions ------------------------------------------------------------
+app.use(session({
+  secret:            process.env.SESSION_SECRET ?? 'dev-secret-change-me',
+  resave:            false,
+  saveUninitialized: false,
+  cookie: {
+    httpOnly: true,
+    secure:   process.env.NODE_ENV === 'production' && process.env.TRUST_PROXY === 'true',
+    maxAge:   8 * 60 * 60 * 1000, // 8 hours
+  },
+}))
+
+// ---- Global locals -------------------------------------------------------
+app.use(injectBrand)
+
+// Inject first-run warning flag when admin password is still the default
+app.use((req, res, next) => {
+  const isAdminRoute = req.path.startsWith('/admin')
+  const isLoggedIn   = (req.session as { isAdmin?: boolean }).isAdmin
+  res.locals.defaultPassword = isAdminRoute && isLoggedIn
+    && (process.env.ADMIN_PASS ?? 'changeme') === 'changeme'
+  next()
+})
+
+// ---- Routes --------------------------------------------------------------
+app.use(authRoutes)
+app.use(adminModelRoutes)
+app.use(adminCategoryRoutes)
+app.use(adminSettingsRoutes)
+app.use(fileRoutes)
+app.use(viewerRoutes)
+
+// ---- Health check --------------------------------------------------------
+app.get('/health', (_req, res) => res.json({ status: 'ok', version: '0.1.0' }))
+
+// ---- 404 -----------------------------------------------------------------
+app.use((_req, res) => {
+  res.status(404).render('error', { status: 404, message: 'Page not found.' })
+})
+
+// ---- Error handler -------------------------------------------------------
+app.use((err: Error, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+  console.error(err)
+  res.status(500).render('error', { status: 500, message: 'An unexpected error occurred.' })
+})
+
+app.listen(PORT, () => {
+  console.log(`StepView running on http://localhost:${PORT}`)
+  console.log(`Admin:    http://localhost:${PORT}/admin`)
+  if ((process.env.ADMIN_PASS ?? 'changeme') === 'changeme') {
+    console.warn('⚠  WARNING: ADMIN_PASS is still set to the default "changeme". Set it in .env before exposing to a network.')
+  }
+})
+
+export default app

src/server/db/index.ts

@@ -0,0 +1,128 @@
+import { DatabaseSync } from 'node:sqlite'
+import bcrypt from 'bcryptjs'
+import path from 'path'
+import fs from 'fs'
+import { SCHEMA_SQL, DEFAULT_SETTINGS } from './schema'
+
+const DATA_DIR = process.env.DATA_DIR ?? path.join(process.cwd(), 'data')
+fs.mkdirSync(DATA_DIR, { recursive: true })
+
+const DB_PATH = path.join(DATA_DIR, 'stepview.db')
+export const db = new DatabaseSync(DB_PATH)
+
+db.exec(SCHEMA_SQL)
+
+// Seed settings that don't yet exist
+const upsertSetting = db.prepare(
+  `INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING`
+)
+for (const [key, value] of Object.entries(DEFAULT_SETTINGS)) {
+  upsertSetting.run(key, value)
+}
+
+// Sync admin password hash from env on every startup
+const envPass = process.env.ADMIN_PASS ?? 'changeme'
+const newHash = bcrypt.hashSync(envPass, 12)
+db.prepare(`UPDATE settings SET value = ? WHERE key = 'admin_pass_hash'`).run(newHash)
+
+// Bootstrap brand name/accent from env only if still at schema defaults
+const envBrandName = process.env.BRAND_NAME
+if (envBrandName) {
+  const current = db.prepare(`SELECT value FROM settings WHERE key = 'brand_name'`).get() as { value: string } | undefined
+  if (current?.value === DEFAULT_SETTINGS.brand_name) {
+    db.prepare(`UPDATE settings SET value = ? WHERE key = 'brand_name'`).run(envBrandName)
+  }
+}
+const envAccent = process.env.BRAND_ACCENT
+if (envAccent) {
+  const current = db.prepare(`SELECT value FROM settings WHERE key = 'brand_accent'`).get() as { value: string } | undefined
+  if (current?.value === DEFAULT_SETTINGS.brand_accent) {
+    db.prepare(`UPDATE settings SET value = ? WHERE key = 'brand_accent'`).run(envAccent)
+  }
+}
+
+// ---- Types ---------------------------------------------------------------
+
+export interface Model {
+  id: number
+  slug: string
+  name: string
+  description: string | null
+  category_id: number | null
+  file_path: string
+  file_type: 'step' | 'stp' | 'stl'
+  thumbnail_path: string | null
+  is_public: 0 | 1
+  created_at: string
+  updated_at: string
+}
+
+export interface Category {
+  id: number
+  name: string
+  slug: string
+  description: string | null
+  sort_order: number
+  created_at: string
+}
+
+export interface ModelPdf {
+  id: number
+  model_id: number
+  display_name: string
+  file_path: string
+  sort_order: number
+}
+
+export interface BrandSettings {
+  brand_name: string
+  brand_tagline: string
+  brand_accent: string
+  brand_logo_path: string
+  brand_favicon_path: string
+}
+
+// ---- Typed query helpers -------------------------------------------------
+// node:sqlite returns Record<string,SQLOutputValue> which requires double-cast
+// to reach our typed interfaces. These helpers centralise that pattern.
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type SqlParam = any
+
+export function q<T>(sql: string) {
+  const stmt = db.prepare(sql)
+  return {
+    all: (...params: SqlParam[]): T[]            => stmt.all(...params) as unknown as T[],
+    get:  (...params: SqlParam[]): T | undefined => stmt.get(...params) as unknown as T | undefined,
+    run:  (...params: SqlParam[])                => stmt.run(...params),
+  }
+}
+
+// ---- Helpers -------------------------------------------------------------
+
+export function getAllSettings(): Record<string, string> {
+  const rows = q<{ key: string; value: string }>(`SELECT key, value FROM settings`).all()
+  return Object.fromEntries(rows.map(r => [r.key, r.value]))
+}
+
+export function getSetting(key: string): string {
+  const row = q<{ value: string }>(`SELECT value FROM settings WHERE key = ?`).get(key)
+  return row?.value ?? ''
+}
+
+export function setSetting(key: string, value: string): void {
+  db.prepare(
+    `INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+  ).run(key, value)
+}
+
+export function getBrandSettings(): BrandSettings {
+  const s = getAllSettings()
+  return {
+    brand_name:         s.brand_name        ?? 'StepView',
+    brand_tagline:      s.brand_tagline      ?? '3D Model Viewer',
+    brand_accent:       s.brand_accent       ?? '#3b82f6',
+    brand_logo_path:    s.brand_logo_path    ?? '',
+    brand_favicon_path: s.brand_favicon_path ?? '',
+  }
+}

src/server/db/schema.ts

@@ -0,0 +1,54 @@
+export const SCHEMA_SQL = `
+PRAGMA journal_mode = WAL;
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS categories (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  name        TEXT NOT NULL,
+  slug        TEXT NOT NULL UNIQUE,
+  description TEXT,
+  sort_order  INTEGER NOT NULL DEFAULT 0,
+  created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS models (
+  id             INTEGER PRIMARY KEY AUTOINCREMENT,
+  slug           TEXT NOT NULL UNIQUE,
+  name           TEXT NOT NULL,
+  description    TEXT,
+  category_id    INTEGER REFERENCES categories(id) ON DELETE SET NULL,
+  file_path      TEXT NOT NULL,
+  file_type      TEXT NOT NULL CHECK(file_type IN ('step', 'stp', 'stl')),
+  thumbnail_path TEXT,
+  is_public      INTEGER NOT NULL DEFAULT 1 CHECK(is_public IN (0, 1)),
+  created_at     TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at     TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS model_pdfs (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  model_id     INTEGER NOT NULL REFERENCES models(id) ON DELETE CASCADE,
+  display_name TEXT NOT NULL,
+  file_path    TEXT NOT NULL,
+  sort_order   INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS settings (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_models_slug        ON models(slug);
+CREATE INDEX IF NOT EXISTS idx_models_category_id ON models(category_id);
+CREATE INDEX IF NOT EXISTS idx_models_is_public   ON models(is_public);
+CREATE INDEX IF NOT EXISTS idx_model_pdfs_model   ON model_pdfs(model_id);
+`
+
+export const DEFAULT_SETTINGS: Record<string, string> = {
+  brand_name:         'StepView',
+  brand_tagline:      '3D Model Viewer',
+  brand_accent:       '#3b82f6',
+  brand_logo_path:    '',
+  brand_favicon_path: '',
+  admin_pass_hash:    '',
+}

src/server/middleware/injectBrand.ts

@@ -0,0 +1,23 @@
+import { Request, Response, NextFunction } from 'express'
+import { getBrandSettings, BrandSettings } from '../db/index'
+
+// Cache brand settings for 60 s so every request doesn't hit SQLite.
+let cache: BrandSettings | null = null
+let cacheExpiresAt = 0
+
+export function injectBrand(_req: Request, res: Response, next: NextFunction): void {
+  const now = Date.now()
+  if (!cache || now > cacheExpiresAt) {
+    cache = getBrandSettings()
+    cacheExpiresAt = now + 60_000
+  }
+  res.locals.brand = cache
+  next()
+}
+
+// Call this whenever brand settings are updated so the next request picks
+// up the changes immediately rather than waiting for the cache to expire.
+export function invalidateBrandCache(): void {
+  cache = null
+  cacheExpiresAt = 0
+}

src/server/middleware/noDownload.ts

@@ -0,0 +1,11 @@
+import { Request, Response, NextFunction } from 'express'
+
+// Applied to all file-serving routes. Prevents browsers from triggering a
+// Save As dialog and strips Accept-Ranges so partial downloads are not possible.
+export function noDownload(_req: Request, res: Response, next: NextFunction): void {
+  res.removeHeader('Content-Disposition')
+  res.setHeader('X-Content-Type-Options', 'nosniff')
+  res.setHeader('Accept-Ranges', 'none')
+  res.setHeader('Cache-Control', 'no-store')
+  next()
+}

src/server/middleware/requireAdmin.ts

@@ -0,0 +1,14 @@
+import { Request, Response, NextFunction } from 'express'
+
+export function requireAdmin(req: Request, res: Response, next: NextFunction): void {
+  if ((req.session as { isAdmin?: boolean }).isAdmin) {
+    next()
+    return
+  }
+  const isApi = req.path.startsWith('/api/')
+  if (isApi) {
+    res.status(401).json({ error: 'Unauthorized' })
+  } else {
+    res.redirect(`/admin/login?next=${encodeURIComponent(req.originalUrl)}`)
+  }
+}

src/server/routes/adminCategories.ts

@@ -0,0 +1,73 @@
+import { Router, Request, Response } from 'express'
+import slugify from 'slugify'
+import { db, q, Category } from '../db/index'
+import { requireAdmin } from '../middleware/requireAdmin'
+
+const router = Router()
+
+router.get('/admin/categories', requireAdmin, (_req: Request, res: Response) => {
+  const categories = q<Category & { model_count: number }>(`
+    SELECT c.*, COUNT(m.id) AS model_count
+    FROM categories c
+    LEFT JOIN models m ON m.category_id = c.id
+    GROUP BY c.id
+    ORDER BY c.sort_order, c.name
+  `).all()
+  res.render('admin/categories', { categories, error: null })
+})
+
+router.post('/admin/categories', requireAdmin, (req: Request, res: Response) => {
+  const { name, description } = req.body as { name: string; description?: string }
+  if (!name?.trim()) {
+    const categories = q<Category & { model_count: number }>(`
+      SELECT *, 0 AS model_count FROM categories ORDER BY sort_order, name
+    `).all()
+    res.render('admin/categories', { categories, error: 'Category name is required.' })
+    return
+  }
+
+  const base = slugify(name.trim(), { lower: true, strict: true })
+  let slug    = base
+  let attempt = 0
+  while (q<{ id: number }>(`SELECT id FROM categories WHERE slug = ?`).get(slug)) {
+    attempt++
+    slug = `${base}-${attempt}`
+  }
+
+  const maxOrder = q<{ m: number | null }>(`SELECT MAX(sort_order) AS m FROM categories`).get()?.m ?? -1
+  db.prepare(`INSERT INTO categories (name, slug, description, sort_order) VALUES (?, ?, ?, ?)`).run(
+    name.trim(), slug, description?.trim() || null, maxOrder + 1
+  )
+  res.redirect('/admin/categories')
+})
+
+router.post('/admin/categories/:id/edit', requireAdmin, (req: Request, res: Response) => {
+  const { name, description } = req.body as { name: string; description?: string }
+  db.prepare(`UPDATE categories SET name = ?, description = ? WHERE id = ?`).run(
+    name.trim(), description?.trim() || null, req.params.id
+  )
+  res.redirect('/admin/categories')
+})
+
+router.post('/admin/categories/:id/delete', requireAdmin, (req: Request, res: Response) => {
+  db.prepare(`DELETE FROM categories WHERE id = ?`).run(req.params.id)
+  res.redirect('/admin/categories')
+})
+
+router.post('/api/admin/categories/reorder', requireAdmin, (req: Request, res: Response) => {
+  const { ids } = req.body as { ids: number[] }
+  if (!Array.isArray(ids)) { res.status(400).json({ error: 'ids must be an array' }); return }
+
+  const update = db.prepare(`UPDATE categories SET sort_order = ? WHERE id = ?`)
+  db.exec('BEGIN')
+  try {
+    ids.forEach((id, index) => update.run(index, id))
+    db.exec('COMMIT')
+  } catch (err) {
+    db.exec('ROLLBACK')
+    throw err
+  }
+  res.json({ ok: true })
+})
+
+export default router

src/server/routes/adminModels.ts

@@ -0,0 +1,259 @@
+import { Router, Request, Response } from 'express'
+import multer from 'multer'
+import path from 'path'
+import fs from 'fs'
+import slugify from 'slugify'
+import { db, q, Model, Category, ModelPdf } from '../db/index'
+import { requireAdmin } from '../middleware/requireAdmin'
+import { convertStepFile, geometryOutputPath } from '../services/stepConverter'
+
+const UPLOADS_DIR = process.env.UPLOADS_DIR ?? path.join(process.cwd(), 'uploads')
+const MAX_FILE_BYTES = parseInt(process.env.MAX_FILE_MB ?? '500', 10) * 1024 * 1024
+
+const ALLOWED_MODEL_EXTS = new Set(['.step', '.stp', '.stl'])
+const ALLOWED_PDF_EXTS   = new Set(['.pdf'])
+
+const modelStorage = multer.diskStorage({
+  destination: path.join(UPLOADS_DIR, 'models'),
+  filename: (_req, file, cb) => {
+    const ext  = path.extname(file.originalname).toLowerCase()
+    const base = slugify(path.basename(file.originalname, ext), { lower: true, strict: true })
+    cb(null, `${Date.now()}-${base}${ext}`)
+  },
+})
+
+const pdfStorage = multer.diskStorage({
+  destination: path.join(UPLOADS_DIR, 'pdfs'),
+  filename: (_req, file, cb) => {
+    const base = slugify(path.basename(file.originalname, '.pdf'), { lower: true, strict: true })
+    cb(null, `${Date.now()}-${base}.pdf`)
+  },
+})
+
+function modelFileFilter(_req: Request, file: Express.Multer.File, cb: multer.FileFilterCallback) {
+  const ext = path.extname(file.originalname).toLowerCase()
+  if (ALLOWED_MODEL_EXTS.has(ext)) cb(null, true)
+  else cb(new Error(`Unsupported file type: ${ext}`))
+}
+
+function pdfFileFilter(_req: Request, file: Express.Multer.File, cb: multer.FileFilterCallback) {
+  const ext = path.extname(file.originalname).toLowerCase()
+  if (ALLOWED_PDF_EXTS.has(ext)) cb(null, true)
+  else cb(new Error('Only PDF files are allowed'))
+}
+
+const uploadModel = multer({ storage: modelStorage, fileFilter: modelFileFilter, limits: { fileSize: MAX_FILE_BYTES } })
+const uploadPdf   = multer({ storage: pdfStorage,   fileFilter: pdfFileFilter,   limits: { fileSize: MAX_FILE_BYTES } })
+
+const router = Router()
+
+// ---- Dashboard -----------------------------------------------------------
+
+router.get('/admin', requireAdmin, (req: Request, res: Response) => {
+  // Use `search` as the query param name to avoid collision with the `q`
+  // helper imported from db/index.
+  const { search, category_id, visibility } = req.query as Record<string, string>
+
+  let sql = `
+    SELECT m.*, c.name AS category_name,
+           (SELECT COUNT(*) FROM model_pdfs WHERE model_id = m.id) AS pdf_count
+    FROM models m
+    LEFT JOIN categories c ON c.id = m.category_id
+    WHERE 1=1
+  `
+  const params: string[] = []
+
+  if (search) {
+    sql += ` AND (m.name LIKE ? OR m.description LIKE ?)`
+    params.push(`%${search}%`, `%${search}%`)
+  }
+  if (category_id) {
+    sql += ` AND m.category_id = ?`
+    params.push(category_id)
+  }
+  if (visibility === 'public')  sql += ` AND m.is_public = 1`
+  if (visibility === 'private') sql += ` AND m.is_public = 0`
+  sql += ` ORDER BY m.created_at DESC`
+
+  const models     = q<Model & { category_name: string | null; pdf_count: number }>(sql).all(...params)
+  const categories = q<Category>(`SELECT * FROM categories ORDER BY sort_order, name`).all()
+  const totalCount  = (q<{ n: number }>(`SELECT COUNT(*) AS n FROM models`).get())?.n ?? 0
+  const publicCount = (q<{ n: number }>(`SELECT COUNT(*) AS n FROM models WHERE is_public = 1`).get())?.n ?? 0
+
+  res.render('admin/dashboard', {
+    models,
+    categories,
+    totalCount,
+    publicCount,
+    filters: { search, category_id, visibility },
+    baseUrl: process.env.BASE_URL ?? `http://localhost:${process.env.PORT ?? 3000}`,
+  })
+})
+
+// ---- Upload form ---------------------------------------------------------
+
+router.get('/admin/upload', requireAdmin, (_req: Request, res: Response) => {
+  const categories = q<Category>(`SELECT * FROM categories ORDER BY sort_order, name`).all()
+  res.render('admin/upload', { categories, error: null })
+})
+
+router.post('/admin/models',
+  requireAdmin,
+  uploadModel.single('model_file'),
+  async (req: Request, res: Response) => {
+    try {
+      if (!req.file) {
+        const categories = q<Category>(`SELECT * FROM categories ORDER BY sort_order, name`).all()
+        res.render('admin/upload', { categories, error: 'A model file is required.' })
+        return
+      }
+
+      const { name, description, category_id, is_public } = req.body as {
+        name: string; description?: string; category_id?: string; is_public?: string
+      }
+
+      const ext  = path.extname(req.file.originalname).toLowerCase().replace('.', '') as 'step' | 'stp' | 'stl'
+      const base = slugify(name, { lower: true, strict: true })
+      let slug   = base
+
+      let attempt = 0
+      while (q<{ id: number }>(`SELECT id FROM models WHERE slug = ?`).get(slug)) {
+        attempt++
+        slug = `${base}-${attempt}`
+      }
+
+      const relPath = path.relative(UPLOADS_DIR, req.file.path).replace(/\\/g, '/')
+
+      db.prepare(`
+        INSERT INTO models (slug, name, description, category_id, file_path, file_type, is_public)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(slug, name.trim(), description?.trim() || null, category_id ? parseInt(category_id, 10) : null, relPath, ext, is_public === 'on' ? 1 : 0)
+
+      // Convert STEP/STP to pre-processed geometry JSON so the browser never
+      // needs to download the 22 MB WASM parser.
+      if (ext === 'step' || ext === 'stp') {
+        const absModelPath = path.join(UPLOADS_DIR, relPath)
+        const geoOutPath   = geometryOutputPath(absModelPath)
+        try {
+          await convertStepFile(absModelPath, geoOutPath)
+        } catch (convErr) {
+          // Conversion failure is non-fatal — the model is saved; the viewer
+          // will show a friendly error instead of crashing the upload.
+          console.error('[stepConverter] conversion failed:', (convErr as Error).message)
+        }
+      }
+
+      res.redirect('/admin')
+    } catch (err) {
+      const categories = q<Category>(`SELECT * FROM categories ORDER BY sort_order, name`).all()
+      res.render('admin/upload', { categories, error: (err as Error).message })
+    }
+  }
+)
+
+// ---- Attach PDF ----------------------------------------------------------
+
+router.post('/admin/models/:id/pdf',
+  requireAdmin,
+  uploadPdf.single('pdf_file'),
+  (req: Request, res: Response) => {
+    const model = q<Model>(`SELECT id FROM models WHERE id = ?`).get(req.params.id)
+    if (!model || !req.file) { res.redirect('/admin'); return }
+
+    const relPath     = path.relative(UPLOADS_DIR, req.file.path).replace(/\\/g, '/')
+    const displayName = (req.body.display_name as string | undefined)?.trim() || req.file.originalname
+    const maxOrder    = q<{ m: number | null }>(`SELECT MAX(sort_order) AS m FROM model_pdfs WHERE model_id = ?`).get(model.id)?.m ?? -1
+
+    db.prepare(`INSERT INTO model_pdfs (model_id, display_name, file_path, sort_order) VALUES (?, ?, ?, ?)`).run(model.id, displayName, relPath, maxOrder + 1)
+    res.redirect(`/admin/models/${model.id}/edit`)
+  }
+)
+
+// ---- Toggle visibility (JSON) --------------------------------------------
+
+router.post('/api/admin/models/:id/visibility', requireAdmin, (req: Request, res: Response) => {
+  const model = q<Model>(`SELECT id, is_public FROM models WHERE id = ?`).get(req.params.id)
+  if (!model) { res.status(404).json({ error: 'Not found' }); return }
+
+  const newValue = model.is_public === 1 ? 0 : 1
+  db.prepare(`UPDATE models SET is_public = ?, updated_at = datetime('now') WHERE id = ?`).run(newValue, model.id)
+  res.json({ is_public: newValue })
+})
+
+// ---- Delete model --------------------------------------------------------
+
+router.post('/admin/models/:id/delete', requireAdmin, (req: Request, res: Response) => {
+  const model = q<Model>(`SELECT * FROM models WHERE id = ?`).get(req.params.id)
+  if (!model) { res.redirect('/admin'); return }
+
+  const modelFile = path.join(UPLOADS_DIR, model.file_path)
+  if (fs.existsSync(modelFile)) fs.unlinkSync(modelFile)
+
+  const pdfs = q<{ file_path: string }>(`SELECT file_path FROM model_pdfs WHERE model_id = ?`).all(model.id)
+  for (const pdf of pdfs) {
+    const pdfFile = path.join(UPLOADS_DIR, pdf.file_path)
+    if (fs.existsSync(pdfFile)) fs.unlinkSync(pdfFile)
+  }
+
+  if (model.thumbnail_path) {
+    const thumb = path.join(UPLOADS_DIR, model.thumbnail_path)
+    if (fs.existsSync(thumb)) fs.unlinkSync(thumb)
+  }
+
+  db.prepare(`DELETE FROM models WHERE id = ?`).run(model.id)
+  res.redirect('/admin')
+})
+
+// ---- Edit model ----------------------------------------------------------
+
+router.get('/admin/models/:id/edit', requireAdmin, (req: Request, res: Response) => {
+  const model = q<Model>(`SELECT * FROM models WHERE id = ?`).get(req.params.id)
+  if (!model) { res.redirect('/admin'); return }
+
+  const categories = q<Category>(`SELECT * FROM categories ORDER BY sort_order, name`).all()
+  const pdfs       = q<ModelPdf>(`SELECT * FROM model_pdfs WHERE model_id = ? ORDER BY sort_order`).all(model.id)
+  res.render('admin/edit', {
+    model, categories, pdfs, error: null,
+    baseUrl: process.env.BASE_URL ?? `http://localhost:${process.env.PORT ?? 3000}`,
+  })
+})
+
+router.post('/admin/models/:id/edit', requireAdmin, (req: Request, res: Response) => {
+  const model = q<Model>(`SELECT * FROM models WHERE id = ?`).get(req.params.id)
+  if (!model) { res.redirect('/admin'); return }
+
+  const { name, description, category_id, is_public } = req.body as {
+    name: string; description?: string; category_id?: string; is_public?: string
+  }
+
+  db.prepare(`UPDATE models SET name = ?, description = ?, category_id = ?, is_public = ?, updated_at = datetime('now') WHERE id = ?`).run(
+    name.trim(), description?.trim() || null, category_id ? parseInt(category_id, 10) : null, is_public === 'on' ? 1 : 0, model.id
+  )
+  res.redirect('/admin')
+})
+
+// ---- Delete PDF ----------------------------------------------------------
+
+router.post('/admin/pdfs/:id/delete', requireAdmin, (req: Request, res: Response) => {
+  const pdf = q<ModelPdf>(`SELECT * FROM model_pdfs WHERE id = ?`).get(req.params.id)
+  if (!pdf) { res.redirect('/admin'); return }
+
+  const pdfFile = path.join(UPLOADS_DIR, pdf.file_path)
+  if (fs.existsSync(pdfFile)) fs.unlinkSync(pdfFile)
+
+  db.prepare(`DELETE FROM model_pdfs WHERE id = ?`).run(pdf.id)
+  res.redirect(`/admin/models/${pdf.model_id}/edit`)
+})
+
+// ---- JSON list -----------------------------------------------------------
+
+router.get('/api/admin/models', requireAdmin, (_req: Request, res: Response) => {
+  const models = q<Model & { category_name: string | null }>(`
+    SELECT m.*, c.name AS category_name
+    FROM models m LEFT JOIN categories c ON c.id = m.category_id
+    ORDER BY m.created_at DESC
+  `).all()
+  res.json(models)
+})
+
+export default router

src/server/routes/adminSettings.ts

@@ -0,0 +1,82 @@
+import { Router, Request, Response } from 'express'
+import multer from 'multer'
+import path from 'path'
+import fs from 'fs'
+import { getAllSettings, setSetting } from '../db/index'
+import { requireAdmin } from '../middleware/requireAdmin'
+import { invalidateBrandCache } from '../middleware/injectBrand'
+
+const UPLOADS_DIR = process.env.UPLOADS_DIR ?? path.join(process.cwd(), 'uploads')
+
+const logoStorage = multer.diskStorage({
+  destination: path.join(UPLOADS_DIR, 'brand'),
+  filename: (_req, file, cb) => {
+    const ext = path.extname(file.originalname).toLowerCase()
+    cb(null, `logo${ext}`)
+  },
+})
+
+const faviconStorage = multer.diskStorage({
+  destination: path.join(UPLOADS_DIR, 'brand'),
+  filename: (_req, file, cb) => {
+    const ext = path.extname(file.originalname).toLowerCase()
+    cb(null, `favicon${ext}`)
+  },
+})
+
+const ALLOWED_IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.svg', '.webp', '.ico'])
+
+function imageFilter(_req: Request, file: Express.Multer.File, cb: multer.FileFilterCallback) {
+  const ext = path.extname(file.originalname).toLowerCase()
+  if (ALLOWED_IMAGE_EXTS.has(ext)) cb(null, true)
+  else cb(new Error('Only image files are allowed for logo/favicon'))
+}
+
+const uploadLogo    = multer({ storage: logoStorage,    fileFilter: imageFilter, limits: { fileSize: 2 * 1024 * 1024 } })
+const uploadFavicon = multer({ storage: faviconStorage, fileFilter: imageFilter, limits: { fileSize: 512 * 1024 } })
+
+const router = Router()
+
+router.get('/admin/settings', requireAdmin, (_req: Request, res: Response) => {
+  const settings = getAllSettings()
+  res.render('admin/settings', { settings, saved: false, error: null })
+})
+
+router.post('/admin/settings', requireAdmin, (req: Request, res: Response) => {
+  const allowed = ['brand_name', 'brand_tagline', 'brand_accent'] as const
+  for (const key of allowed) {
+    const val = (req.body as Record<string, string>)[key]?.trim()
+    if (val !== undefined) setSetting(key, val)
+  }
+  invalidateBrandCache()
+  const settings = getAllSettings()
+  res.render('admin/settings', { settings, saved: true, error: null })
+})
+
+router.post('/admin/settings/logo', requireAdmin, uploadLogo.single('logo'), (_req: Request, res: Response) => {
+  if (_req.file) {
+    setSetting('brand_logo_path', `brand/${_req.file.filename}`)
+    invalidateBrandCache()
+  }
+  res.redirect('/admin/settings')
+})
+
+router.post('/admin/settings/favicon', requireAdmin, uploadFavicon.single('favicon'), (req: Request, res: Response) => {
+  if (req.file) {
+    setSetting('brand_favicon_path', `brand/${req.file.filename}`)
+    invalidateBrandCache()
+  }
+  res.redirect('/admin/settings')
+})
+
+router.post('/admin/settings/logo/delete', requireAdmin, (_req: Request, res: Response) => {
+  for (const ext of ['.png', '.jpg', '.jpeg', '.svg', '.webp']) {
+    const f = path.join(UPLOADS_DIR, 'brand', `logo${ext}`)
+    if (fs.existsSync(f)) fs.unlinkSync(f)
+  }
+  setSetting('brand_logo_path', '')
+  invalidateBrandCache()
+  res.redirect('/admin/settings')
+})
+
+export default router

src/server/routes/auth.ts

@@ -0,0 +1,47 @@
+import { Router, Request, Response } from 'express'
+import bcrypt from 'bcryptjs'
+import { getSetting } from '../db/index'
+
+const router = Router()
+
+router.get('/admin/login', (req: Request, res: Response) => {
+  if ((req.session as { isAdmin?: boolean }).isAdmin) {
+    res.redirect('/admin')
+    return
+  }
+  res.render('admin/login', {
+    error: null,
+    next: req.query.next ?? '/admin',
+  })
+})
+
+router.post('/admin/login', async (req: Request, res: Response) => {
+  const { username, password } = req.body as { username: string; password: string }
+  const expectedUser = process.env.ADMIN_USER ?? 'admin'
+  const storedHash   = getSetting('admin_pass_hash')
+
+  const userMatch = username === expectedUser
+  const passMatch = storedHash ? await bcrypt.compare(password, storedHash) : false
+
+  if (userMatch && passMatch) {
+    ;(req.session as { isAdmin?: boolean }).isAdmin = true
+    const next = (req.body.next as string | undefined) ?? '/admin'
+    // Guard against open redirect
+    const safeNext = next.startsWith('/') ? next : '/admin'
+    res.redirect(safeNext)
+    return
+  }
+
+  res.render('admin/login', {
+    error: 'Invalid username or password.',
+    next: req.body.next ?? '/admin',
+  })
+})
+
+router.post('/admin/logout', (req: Request, res: Response) => {
+  req.session.destroy(() => {
+    res.redirect('/admin/login')
+  })
+})
+
+export default router

src/server/routes/files.ts

@@ -0,0 +1,124 @@
+import { Router, Request, Response } from 'express'
+import path from 'path'
+import fs from 'fs'
+import { q, Model, ModelPdf, getSetting } from '../db/index'
+import { noDownload } from '../middleware/noDownload'
+import { geometryOutputPath } from '../services/stepConverter'
+
+const UPLOADS_DIR = process.env.UPLOADS_DIR ?? path.join(process.cwd(), 'uploads')
+
+const router = Router()
+
+function safeResolve(relPath: string): string | null {
+  const abs = path.resolve(UPLOADS_DIR, relPath)
+  if (!abs.startsWith(path.resolve(UPLOADS_DIR))) return null
+  return abs
+}
+
+router.get('/files/model/:id', noDownload, (req: Request, res: Response) => {
+  const model = q<Model>(`SELECT * FROM models WHERE id = ?`).get(req.params.id)
+  if (!model) { res.status(404).end(); return }
+
+  if (!model.is_public && !(req.session as { isAdmin?: boolean }).isAdmin) {
+    res.status(403).end(); return
+  }
+
+  const abs = safeResolve(model.file_path)
+  if (!abs || !fs.existsSync(abs)) { res.status(404).end(); return }
+
+  const ext  = path.extname(model.file_path).toLowerCase()
+  const mime = ext === '.stl' ? 'model/stl' : 'application/octet-stream'
+  res.setHeader('Content-Type', mime)
+  fs.createReadStream(abs).pipe(res)
+})
+
+router.get('/files/pdf/:modelId/:pdfId', noDownload, (req: Request, res: Response) => {
+  const model = q<{ is_public: 0 | 1 }>(`SELECT is_public FROM models WHERE id = ?`).get(req.params.modelId)
+  if (!model) { res.status(404).end(); return }
+
+  if (!model.is_public && !(req.session as { isAdmin?: boolean }).isAdmin) {
+    res.status(403).end(); return
+  }
+
+  const pdf = q<ModelPdf>(`SELECT * FROM model_pdfs WHERE id = ? AND model_id = ?`).get(req.params.pdfId, req.params.modelId)
+  if (!pdf) { res.status(404).end(); return }
+
+  const abs = safeResolve(pdf.file_path)
+  if (!abs || !fs.existsSync(abs)) { res.status(404).end(); return }
+
+  res.setHeader('Content-Type', 'application/pdf')
+  fs.createReadStream(abs).pipe(res)
+})
+
+router.get('/brand/logo', (_req: Request, res: Response) => {
+  const relPath = getSetting('brand_logo_path')
+  if (!relPath) { res.status(404).end(); return }
+
+  const abs = safeResolve(relPath)
+  if (!abs || !fs.existsSync(abs)) { res.status(404).end(); return }
+
+  const ext  = path.extname(abs).toLowerCase()
+  const mimeMap: Record<string, string> = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.svg': 'image/svg+xml', '.webp': 'image/webp', '.ico': 'image/x-icon',
+  }
+  res.setHeader('Content-Type', mimeMap[ext] ?? 'application/octet-stream')
+  res.setHeader('Cache-Control', 'public, max-age=3600')
+  fs.createReadStream(abs).pipe(res)
+})
+
+router.get('/brand/favicon', (_req: Request, res: Response) => {
+  const relPath = getSetting('brand_favicon_path')
+  if (!relPath) { res.status(404).end(); return }
+
+  const abs = safeResolve(relPath)
+  if (!abs || !fs.existsSync(abs)) { res.status(404).end(); return }
+
+  res.setHeader('Content-Type', 'image/x-icon')
+  res.setHeader('Cache-Control', 'public, max-age=86400')
+  fs.createReadStream(abs).pipe(res)
+})
+
+// Pre-processed geometry JSON for STEP/STP files (served with gzip by compression middleware)
+router.get('/files/geometry/:id', (req: Request, res: Response) => {
+  const model = q<Model>(`SELECT * FROM models WHERE id = ?`).get(req.params.id)
+  if (!model) { res.status(404).json({ error: 'Not found' }); return }
+
+  if (!model.is_public && !(req.session as { isAdmin?: boolean }).isAdmin) {
+    res.status(403).json({ error: 'Forbidden' }); return
+  }
+
+  const absModelPath = safeResolve(model.file_path)
+  if (!absModelPath) { res.status(404).json({ error: 'Model file not found' }); return }
+
+  const geoPath = geometryOutputPath(absModelPath)
+  if (!fs.existsSync(geoPath)) {
+    res.status(404).json({ error: 'Geometry not yet processed', processing: true })
+    return
+  }
+
+  res.setHeader('Content-Type', 'application/json')
+  res.setHeader('Cache-Control', 'public, max-age=3600')
+  fs.createReadStream(geoPath).pipe(res)
+})
+
+router.get('/files/thumbnail/:id', (req: Request, res: Response) => {
+  const model = q<Pick<Model, 'thumbnail_path' | 'is_public'>>(
+    `SELECT thumbnail_path, is_public FROM models WHERE id = ?`
+  ).get(req.params.id)
+
+  if (!model?.thumbnail_path) { res.status(404).end(); return }
+
+  if (!model.is_public && !(req.session as { isAdmin?: boolean }).isAdmin) {
+    res.status(403).end(); return
+  }
+
+  const abs = safeResolve(model.thumbnail_path)
+  if (!abs || !fs.existsSync(abs)) { res.status(404).end(); return }
+
+  res.setHeader('Content-Type', 'image/png')
+  res.setHeader('Cache-Control', 'public, max-age=3600')
+  fs.createReadStream(abs).pipe(res)
+})
+
+export default router

src/server/routes/viewer.ts

@@ -0,0 +1,79 @@
+import { Router, Request, Response } from 'express'
+import path from 'path'
+import fs from 'fs'
+import { q, Model, ModelPdf, Category } from '../db/index'
+import { geometryOutputPath } from '../services/stepConverter'
+
+const UPLOADS_DIR = process.env.UPLOADS_DIR ?? path.join(process.cwd(), 'uploads')
+
+const router = Router()
+
+router.get('/view/:slug', (req: Request, res: Response) => {
+  const model = q<Model & { category_name: string | null }>(`
+    SELECT m.*, c.name AS category_name
+    FROM models m
+    LEFT JOIN categories c ON c.id = m.category_id
+    WHERE m.slug = ?
+  `).get(req.params.slug)
+
+  if (!model) {
+    res.status(404).render('error', { status: 404, message: 'Model not found.' })
+    return
+  }
+
+  if (!model.is_public && !(req.session as { isAdmin?: boolean }).isAdmin) {
+    res.status(403).render('error', { status: 403, message: 'This model is not publicly available.' })
+    return
+  }
+
+  const pdfs    = q<ModelPdf>(`SELECT * FROM model_pdfs WHERE model_id = ? ORDER BY sort_order`).all(model.id)
+  const baseUrl = process.env.BASE_URL ?? `http://localhost:${process.env.PORT ?? 3000}`
+
+  // Determine whether pre-processed geometry is available for STEP/STP
+  let hasGeometry = false
+  if (model.file_type === 'step' || model.file_type === 'stp') {
+    const absPath = path.resolve(UPLOADS_DIR, model.file_path)
+    hasGeometry   = fs.existsSync(geometryOutputPath(absPath))
+  }
+
+  res.render('viewer', {
+    model,
+    pdfs,
+    shareUrl:    `${baseUrl}/view/${model.slug}`,
+    hasGeometry,
+  })
+})
+
+// ---- Public model index --------------------------------------------------
+
+router.get('/', (_req: Request, res: Response) => {
+  // Fetch categories that have at least one public model, plus their models
+  const categories = q<Category & { model_count: number }>(`
+    SELECT c.*, COUNT(m.id) AS model_count
+    FROM categories c
+    INNER JOIN models m ON m.category_id = c.id AND m.is_public = 1
+    GROUP BY c.id
+    HAVING model_count > 0
+    ORDER BY c.sort_order, c.name
+  `).all()
+
+  // For each category, fetch its models
+  const categorised = categories.map(cat => ({
+    category: cat,
+    models:   q<Model>(`
+      SELECT * FROM models
+      WHERE is_public = 1 AND category_id = ?
+      ORDER BY created_at DESC
+    `).all(cat.id),
+  }))
+
+  const uncategorized = q<Model>(`
+    SELECT * FROM models
+    WHERE is_public = 1 AND category_id IS NULL
+    ORDER BY created_at DESC
+  `).all()
+
+  res.render('index', { categorised, uncategorized })
+})
+
+export default router

src/server/services/stepConverter.ts

@@ -0,0 +1,68 @@
+import occtimport from 'occt-import-js'
+import fs from 'fs'
+import path from 'path'
+
+export interface GeometryMesh {
+  positions: number[]
+  normals:   number[] | null
+  indices:   number[]
+  color:     [number, number, number] | null
+}
+
+export interface GeometryFile {
+  version:    1
+  sourceFile: string
+  meshCount:  number
+  meshes:     GeometryMesh[]
+}
+
+// Singleton — WASM initializes once per Node process (~3 s on first call, instant after)
+let _occt: Awaited<ReturnType<typeof occtimport>> | null = null
+let _init: Promise<Awaited<ReturnType<typeof occtimport>>> | null = null
+
+async function getOcct() {
+  if (_occt) return _occt
+  if (!_init) _init = occtimport().then(m => { _occt = m; return m })
+  return _init
+}
+
+// Warm up the WASM module in the background so the first upload doesn't pay
+// the initialization cost during the HTTP request.
+export function warmUpOcct(): void {
+  getOcct().catch(() => {/* non-fatal */})
+}
+
+export async function convertStepFile(
+  inputPath: string,
+  outputPath: string,
+): Promise<{ meshCount: number }> {
+  const occt   = await getOcct()
+  const buffer = fs.readFileSync(inputPath)
+  const result = occt.ReadStepFile(new Uint8Array(buffer), null)
+
+  if (!result.success || result.meshes.length === 0) {
+    throw new Error('STEP/STP parse failed — file may be corrupt or unsupported.')
+  }
+
+  const geo: GeometryFile = {
+    version:    1,
+    sourceFile: path.basename(inputPath),
+    meshCount:  result.meshes.length,
+    meshes: result.meshes.map(mesh => ({
+      positions: Array.from(mesh.attributes.position.array),
+      normals:   mesh.attributes.normal ? Array.from(mesh.attributes.normal.array) : null,
+      indices:   Array.from(mesh.index.array),
+      color:     mesh.color ? [mesh.color[0], mesh.color[1], mesh.color[2]] : null,
+    })),
+  }
+
+  fs.writeFileSync(outputPath, JSON.stringify(geo))
+  return { meshCount: result.meshes.length }
+}
+
+/** Returns the expected geometry output path for a given model file path. */
+export function geometryOutputPath(modelFilePath: string): string {
+  const dir  = path.dirname(modelFilePath)
+  const base = path.basename(modelFilePath, path.extname(modelFilePath))
+  return path.join(dir, `${base}.geometry.json`)
+}

src/server/types/occt-import-js.d.ts

@@ -0,0 +1,20 @@
+declare module 'occt-import-js' {
+  interface MeshAttributes {
+    position: { array: Float32Array }
+    normal?:  { array: Float32Array }
+  }
+  interface OcctMesh {
+    attributes: MeshAttributes
+    index:      { array: Uint32Array }
+    color:      number[] | null
+  }
+  interface ReadResult {
+    success: boolean
+    meshes:  OcctMesh[]
+  }
+  interface OcctModule {
+    ReadStepFile(buffer: Uint8Array, params: null): ReadResult
+  }
+  function occtimport(options?: { locateFile?: (f: string) => string }): Promise<OcctModule>
+  export default occtimport
+}

tailwind.config.ts

@@ -0,0 +1,27 @@
+import type { Config } from 'tailwindcss'
+
+export default {
+  darkMode: 'class',
+  content: [
+    './views/**/*.ejs',
+    './src/client/**/*.ts',
+  ],
+  theme: {
+    extend: {
+      colors: {
+        surface: {
+          950: '#0a0a0f',
+          900: '#111118',
+          800: '#1a1a24',
+          700: '#24242f',
+          600: '#2e2e3a',
+        },
+      },
+      fontFamily: {
+        sans: ['Inter', 'system-ui', 'sans-serif'],
+        mono: ['JetBrains Mono', 'monospace'],
+      },
+    },
+  },
+  plugins: [],
+} satisfies Config

tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "baseUrl": ".",
+    "paths": {
+      "@server/*": ["src/server/*"],
+      "@client/*": ["src/client/*"]
+    }
+  }
+}

tsconfig.server.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "dist/server",
+    "lib": ["ES2022"],
+    "paths": {
+      "@server/*": ["src/server/*"]
+    }
+  },
+  "include": ["src/server/**/*"],
+  "exclude": ["node_modules", "dist", "public", "src/client"]
+}

views/admin/categories.ejs

@@ -0,0 +1,84 @@
+<%- include('../partials/head', { title: 'Categories' }) %>
+<%- include('../partials/adminNav', { currentPath: '/admin/categories' }) %>
+
+<div class="pl-56 min-h-screen">
+  <%- include('../partials/adminBanner') %>
+  <div class="max-w-2xl mx-auto px-8 py-8">
+    <div class="mb-8">
+      <h1 class="text-xl font-semibold text-white">Categories</h1>
+      <p class="text-sm text-gray-500 mt-0.5">Organize your models into groups</p>
+    </div>
+
+    <% if (error) { %>
+    <div class="mb-6 flex items-start gap-3 bg-red-500/10 border border-red-500/30 rounded-lg px-4 py-3">
+      <p class="text-sm text-red-400"><%= error %></p>
+    </div>
+    <% } %>
+
+    <!-- New category form -->
+    <form method="POST" action="/admin/categories" class="bg-surface-900 border border-gray-800 rounded-2xl p-6 mb-6">
+      <h2 class="text-sm font-semibold text-white mb-4">New Category</h2>
+      <div class="flex gap-3">
+        <input name="name" type="text" required placeholder="Category name"
+          class="flex-1 bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent transition-colors" />
+        <input name="description" type="text" placeholder="Description (optional)"
+          class="flex-1 bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent transition-colors" />
+        <button type="submit" class="btn-accent text-white rounded-lg px-5 py-2 text-sm font-medium transition-all shrink-0">
+          Add
+        </button>
+      </div>
+    </form>
+
+    <!-- Category list -->
+    <% if (categories.length === 0) { %>
+    <div class="bg-surface-900 border border-gray-800 rounded-2xl px-8 py-12 text-center">
+      <p class="text-sm text-gray-500">No categories yet. Create one above.</p>
+    </div>
+    <% } else { %>
+    <div class="bg-surface-900 border border-gray-800 rounded-2xl overflow-hidden">
+      <% categories.forEach((cat, i) => { %>
+      <div class="<%= i > 0 ? 'border-t border-gray-800' : '' %> px-5 py-4 flex items-center gap-4 hover:bg-surface-800 transition-colors group">
+        <div class="flex-1 min-w-0">
+          <p class="text-sm font-medium text-white"><%= cat.name %></p>
+          <% if (cat.description) { %>
+          <p class="text-xs text-gray-500 mt-0.5"><%= cat.description %></p>
+          <% } %>
+        </div>
+        <span class="text-xs text-gray-600 shrink-0"><%= cat.model_count %> model<%= cat.model_count !== 1 ? 's' : '' %></span>
+
+        <!-- Inline edit form (hidden by default) -->
+        <form method="POST" action="/admin/categories/<%= cat.id %>/edit" class="hidden edit-form gap-2 items-center">
+          <input name="name" value="<%= cat.name %>" type="text" required
+            class="bg-surface-700 border border-gray-600 rounded-lg px-3 py-1.5 text-sm text-white focus:outline-none focus:border-accent w-40 transition-colors" />
+          <input name="description" value="<%= cat.description || '' %>" type="text" placeholder="Description"
+            class="bg-surface-700 border border-gray-600 rounded-lg px-3 py-1.5 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent w-44 transition-colors" />
+          <button type="submit" class="text-xs btn-accent text-white rounded-lg px-3 py-1.5">Save</button>
+          <button type="button" class="text-xs text-gray-500 hover:text-white cancel-edit">Cancel</button>
+        </form>
+
+        <!-- Action buttons -->
+        <div class="flex items-center gap-1 action-buttons">
+          <button type="button" class="edit-btn p-1.5 rounded-lg text-gray-500 hover:text-white hover:bg-surface-700 transition-colors" title="Rename">
+            <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M16.862 4.487l1.687-1.688a1.875 1.875 0 112.652 2.652L10.582 16.07a4.5 4.5 0 01-1.897 1.13L6 18l.8-2.685a4.5 4.5 0 011.13-1.897l8.932-8.931z" />
+            </svg>
+          </button>
+          <form method="POST" action="/admin/categories/<%= cat.id %>/delete"
+            onsubmit="return confirm('Delete «<%= cat.name %>»? Models in this category will become uncategorized.')">
+            <button type="submit" class="p-1.5 rounded-lg text-gray-500 hover:text-red-400 hover:bg-red-500/10 transition-colors" title="Delete">
+              <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M14.74 9l-.346 9m-4.788 0L9.26 9m9.968-3.21c.342.052.682.107 1.022.166m-1.022-.165L18.16 19.673a2.25 2.25 0 01-2.244 2.077H8.084a2.25 2.25 0 01-2.244-2.077L4.772 5.79m14.456 0a48.108 48.108 0 00-3.478-.397m-12 .562c.34-.059.68-.114 1.022-.165m0 0a48.11 48.11 0 013.478-.397m7.5 0v-.916c0-1.18-.91-2.164-2.09-2.201a51.964 51.964 0 00-3.32 0c-1.18.037-2.09 1.022-2.09 2.201v.916m7.5 0a48.667 48.667 0 00-7.5 0" />
+              </svg>
+            </button>
+          </form>
+        </div>
+      </div>
+      <% }) %>
+    </div>
+    <% } %>
+  </div>
+</div>
+
+<script src="/admin.js"></script>
+</body>
+</html>

views/admin/dashboard.ejs

@@ -0,0 +1,156 @@
+<%- include('../partials/head', { title: 'Models' }) %>
+<%- include('../partials/adminNav', { currentPath: '/admin' }) %>
+
+<div class="pl-56 min-h-screen">
+  <%- include('../partials/adminBanner') %>
+  <div class="max-w-7xl mx-auto px-8 py-8">
+
+    <!-- Page header -->
+    <div class="flex items-center justify-between mb-8">
+      <div>
+        <h1 class="text-xl font-semibold text-white">Models</h1>
+        <p class="text-sm text-gray-500 mt-0.5"><%= totalCount %> total &nbsp;·&nbsp; <%= publicCount %> public</p>
+      </div>
+      <a href="/admin/upload" class="inline-flex items-center gap-2 btn-accent text-white rounded-lg px-4 py-2 text-sm font-medium transition-all">
+        <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M12 4.5v15m7.5-7.5h-15" />
+        </svg>
+        Upload Model
+      </a>
+    </div>
+
+    <!-- Filters -->
+    <form method="GET" action="/admin" class="flex flex-wrap gap-3 mb-6">
+      <input
+        name="search" value="<%= filters.search || '' %>"
+        placeholder="Search models…"
+        class="bg-surface-900 border border-gray-800 rounded-lg px-3.5 py-2 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent w-64 transition-colors"
+      />
+      <select name="category_id" class="bg-surface-900 border border-gray-800 rounded-lg px-3 py-2 text-sm text-gray-300 focus:outline-none focus:border-accent transition-colors">
+        <option value="">All categories</option>
+        <% categories.forEach(c => { %>
+        <option value="<%= c.id %>" <%= filters.category_id == c.id ? 'selected' : '' %>><%= c.name %></option>
+        <% }) %>
+      </select>
+      <select name="visibility" class="bg-surface-900 border border-gray-800 rounded-lg px-3 py-2 text-sm text-gray-300 focus:outline-none focus:border-accent transition-colors">
+        <option value="">All visibility</option>
+        <option value="public"  <%= filters.visibility === 'public'  ? 'selected' : '' %>>Public</option>
+        <option value="private" <%= filters.visibility === 'private' ? 'selected' : '' %>>Private</option>
+      </select>
+      <button type="submit" class="bg-surface-800 hover:bg-surface-700 border border-gray-700 text-sm text-gray-300 rounded-lg px-4 py-2 transition-colors">
+        Filter
+      </button>
+      <% if (filters.search || filters.category_id || filters.visibility) { %>
+      <a href="/admin" class="bg-surface-800 hover:bg-surface-700 border border-gray-700 text-sm text-gray-400 rounded-lg px-4 py-2 transition-colors">
+        Clear
+      </a>
+      <% } %>
+    </form>
+
+    <!-- Table -->
+    <% if (models.length === 0) { %>
+    <div class="bg-surface-900 border border-gray-800 rounded-2xl px-8 py-16 text-center">
+      <svg class="w-12 h-12 text-gray-700 mx-auto mb-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25m9-5.25v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />
+      </svg>
+      <p class="text-gray-500 text-sm">No models yet. <a href="/admin/upload" class="text-accent underline">Upload your first model.</a></p>
+    </div>
+    <% } else { %>
+    <div class="bg-surface-900 border border-gray-800 rounded-2xl overflow-hidden">
+      <table class="w-full text-sm">
+        <thead>
+          <tr class="border-b border-gray-800">
+            <th class="text-left px-5 py-3.5 text-xs font-medium text-gray-500 uppercase tracking-wider">Name</th>
+            <th class="text-left px-5 py-3.5 text-xs font-medium text-gray-500 uppercase tracking-wider hidden md:table-cell">Category</th>
+            <th class="text-left px-5 py-3.5 text-xs font-medium text-gray-500 uppercase tracking-wider hidden lg:table-cell">Type</th>
+            <th class="text-left px-5 py-3.5 text-xs font-medium text-gray-500 uppercase tracking-wider hidden lg:table-cell">PDFs</th>
+            <th class="text-left px-5 py-3.5 text-xs font-medium text-gray-500 uppercase tracking-wider">Visibility</th>
+            <th class="text-right px-5 py-3.5 text-xs font-medium text-gray-500 uppercase tracking-wider">Actions</th>
+          </tr>
+        </thead>
+        <tbody class="divide-y divide-gray-800">
+          <% models.forEach(model => { %>
+          <tr class="hover:bg-surface-800 transition-colors group" data-model-id="<%= model.id %>">
+            <td class="px-5 py-4">
+              <div class="font-medium text-white"><%= model.name %></div>
+              <% if (model.description) { %>
+              <div class="text-xs text-gray-500 mt-0.5 truncate max-w-xs"><%= model.description %></div>
+              <% } %>
+            </td>
+            <td class="px-5 py-4 hidden md:table-cell">
+              <span class="text-gray-400"><%= model.category_name || '—' %></span>
+            </td>
+            <td class="px-5 py-4 hidden lg:table-cell">
+              <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-mono bg-surface-800 border border-gray-700 text-gray-400"><%= model.file_type.toUpperCase() %></span>
+            </td>
+            <td class="px-5 py-4 hidden lg:table-cell text-gray-400">
+              <%= model.pdf_count %>
+            </td>
+            <td class="px-5 py-4">
+              <button
+                type="button"
+                class="visibility-toggle inline-flex items-center gap-1.5 px-2.5 py-1 rounded-full text-xs font-medium border transition-colors cursor-pointer
+                  <%= model.is_public ? 'bg-green-500/10 border-green-500/30 text-green-400' : 'bg-gray-700/50 border-gray-700 text-gray-500' %>"
+                data-model-id="<%= model.id %>"
+                data-is-public="<%= model.is_public %>"
+              >
+                <span class="w-1.5 h-1.5 rounded-full <%= model.is_public ? 'bg-green-400' : 'bg-gray-500' %>"></span>
+                <%= model.is_public ? 'Public' : 'Private' %>
+              </button>
+            </td>
+            <td class="px-5 py-4">
+              <div class="flex items-center justify-end gap-2">
+                <!-- Copy link -->
+                <button
+                  type="button"
+                  title="Copy share link"
+                  class="copy-link-btn p-1.5 rounded-lg text-gray-500 hover:text-white hover:bg-surface-700 transition-colors"
+                  data-url="<%= baseUrl %>/view/<%= model.slug %>"
+                >
+                  <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M13.19 8.688a4.5 4.5 0 011.242 7.244l-4.5 4.5a4.5 4.5 0 01-6.364-6.364l1.757-1.757m13.35-.622l1.757-1.757a4.5 4.5 0 00-6.364-6.364l-4.5 4.5a4.5 4.5 0 001.242 7.244" />
+                  </svg>
+                </button>
+                <!-- View -->
+                <a href="/view/<%= model.slug %>" target="_blank" title="View model"
+                   class="p-1.5 rounded-lg text-gray-500 hover:text-white hover:bg-surface-700 transition-colors">
+                  <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M2.036 12.322a1.012 1.012 0 010-.639C3.423 7.51 7.36 4.5 12 4.5c4.638 0 8.573 3.007 9.963 7.178.07.207.07.431 0 .639C20.577 16.49 16.64 19.5 12 19.5c-4.641 0-8.574-3.007-9.964-7.178z" />
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+                  </svg>
+                </a>
+                <!-- Edit -->
+                <a href="/admin/models/<%= model.id %>/edit" title="Edit model"
+                   class="p-1.5 rounded-lg text-gray-500 hover:text-white hover:bg-surface-700 transition-colors">
+                  <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M16.862 4.487l1.687-1.688a1.875 1.875 0 112.652 2.652L10.582 16.07a4.5 4.5 0 01-1.897 1.13L6 18l.8-2.685a4.5 4.5 0 011.13-1.897l8.932-8.931zm0 0L19.5 7.125M18 14v4.75A2.25 2.25 0 0115.75 21H5.25A2.25 2.25 0 013 18.75V8.25A2.25 2.25 0 015.25 6H10" />
+                  </svg>
+                </a>
+                <!-- Delete -->
+                <form method="POST" action="/admin/models/<%= model.id %>/delete" class="inline" onsubmit="return confirm('Delete «<%= model.name %>»? This cannot be undone.')">
+                  <button type="submit" title="Delete model"
+                     class="p-1.5 rounded-lg text-gray-500 hover:text-red-400 hover:bg-red-500/10 transition-colors">
+                    <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+                      <path stroke-linecap="round" stroke-linejoin="round" d="M14.74 9l-.346 9m-4.788 0L9.26 9m9.968-3.21c.342.052.682.107 1.022.166m-1.022-.165L18.16 19.673a2.25 2.25 0 01-2.244 2.077H8.084a2.25 2.25 0 01-2.244-2.077L4.772 5.79m14.456 0a48.108 48.108 0 00-3.478-.397m-12 .562c.34-.059.68-.114 1.022-.165m0 0a48.11 48.11 0 013.478-.397m7.5 0v-.916c0-1.18-.91-2.164-2.09-2.201a51.964 51.964 0 00-3.32 0c-1.18.037-2.09 1.022-2.09 2.201v.916m7.5 0a48.667 48.667 0 00-7.5 0" />
+                    </svg>
+                  </button>
+                </form>
+              </div>
+            </td>
+          </tr>
+          <% }) %>
+        </tbody>
+      </table>
+    </div>
+    <% } %>
+  </div>
+</div>
+
+<!-- Toast notification -->
+<div id="toast" class="fixed bottom-6 right-6 bg-surface-800 border border-gray-700 text-white text-sm px-4 py-3 rounded-xl shadow-2xl opacity-0 translate-y-2 transition-all duration-300 pointer-events-none z-50">
+  <span id="toast-msg"></span>
+</div>
+
+<script src="/admin.js"></script>
+</body>
+</html>

views/admin/edit.ejs

@@ -0,0 +1,118 @@
+<%- include('../partials/head', { title: 'Edit Model' }) %>
+<%- include('../partials/adminNav', { currentPath: '/admin' }) %>
+
+<div class="pl-56 min-h-screen">
+  <%- include('../partials/adminBanner') %>
+  <div class="max-w-2xl mx-auto px-8 py-8">
+    <div class="flex items-center gap-3 mb-8">
+      <a href="/admin" class="text-gray-500 hover:text-white transition-colors">
+        <svg class="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18" />
+        </svg>
+      </a>
+      <h1 class="text-xl font-semibold text-white">Edit Model</h1>
+    </div>
+
+    <% if (error) { %>
+    <div class="mb-6 flex items-start gap-3 bg-red-500/10 border border-red-500/30 rounded-lg px-4 py-3">
+      <p class="text-sm text-red-400"><%= error %></p>
+    </div>
+    <% } %>
+
+    <!-- Model details form -->
+    <form method="POST" action="/admin/models/<%= model.id %>/edit" class="bg-surface-900 border border-gray-800 rounded-2xl p-6 space-y-5 mb-6">
+      <div>
+        <label class="block text-xs font-medium text-gray-400 mb-1.5">Display Name <span class="text-red-400">*</span></label>
+        <input name="name" type="text" required value="<%= model.name %>"
+          class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white focus:outline-none focus:border-accent transition-colors"
+        />
+      </div>
+      <div>
+        <label class="block text-xs font-medium text-gray-400 mb-1.5">Description</label>
+        <textarea name="description" rows="3"
+          class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent transition-colors resize-none"
+        ><%= model.description || '' %></textarea>
+      </div>
+      <div class="grid grid-cols-2 gap-4">
+        <div>
+          <label class="block text-xs font-medium text-gray-400 mb-1.5">Category</label>
+          <select name="category_id"
+            class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3 py-2.5 text-sm text-gray-300 focus:outline-none focus:border-accent transition-colors">
+            <option value="">Uncategorized</option>
+            <% categories.forEach(c => { %>
+            <option value="<%= c.id %>" <%= model.category_id == c.id ? 'selected' : '' %>><%= c.name %></option>
+            <% }) %>
+          </select>
+        </div>
+        <div class="flex items-end pb-0.5">
+          <label class="flex items-center gap-2.5 cursor-pointer">
+            <div class="relative">
+              <input name="is_public" type="checkbox" <%= model.is_public ? 'checked' : '' %> class="sr-only peer" />
+              <div class="w-9 h-5 bg-gray-700 rounded-full peer-checked:bg-accent transition-colors"></div>
+              <div class="absolute top-0.5 left-0.5 w-4 h-4 bg-white rounded-full transition-transform peer-checked:translate-x-4"></div>
+            </div>
+            <span class="text-sm text-gray-400">Public</span>
+          </label>
+        </div>
+      </div>
+      <div class="pt-2">
+        <button type="submit" class="btn-accent text-white rounded-lg px-5 py-2 text-sm font-medium transition-all">Save Changes</button>
+      </div>
+    </form>
+
+    <!-- Attached PDFs -->
+    <div class="bg-surface-900 border border-gray-800 rounded-2xl p-6 mb-6">
+      <h2 class="text-sm font-semibold text-white mb-4">Shop Diagrams / PDFs</h2>
+      <% if (pdfs.length === 0) { %>
+      <p class="text-sm text-gray-500 mb-4">No PDFs attached yet.</p>
+      <% } else { %>
+      <ul class="space-y-2 mb-4">
+        <% pdfs.forEach(pdf => { %>
+        <li class="flex items-center justify-between bg-surface-800 rounded-lg px-4 py-2.5">
+          <span class="text-sm text-gray-300"><%= pdf.display_name %></span>
+          <form method="POST" action="/admin/pdfs/<%= pdf.id %>/delete" onsubmit="return confirm('Remove this PDF?')">
+            <button type="submit" class="text-xs text-gray-500 hover:text-red-400 transition-colors">Remove</button>
+          </form>
+        </li>
+        <% }) %>
+      </ul>
+      <% } %>
+      <form method="POST" action="/admin/models/<%= model.id %>/pdf" enctype="multipart/form-data" class="flex gap-3 items-end">
+        <div class="flex-1">
+          <label class="block text-xs font-medium text-gray-400 mb-1.5">Attach PDF</label>
+          <input type="file" name="pdf_file" accept=".pdf" required
+            class="w-full text-sm text-gray-400 file:mr-3 file:py-1.5 file:px-3 file:rounded-lg file:border-0 file:text-xs file:font-medium file:bg-surface-700 file:text-gray-300 hover:file:bg-surface-600 transition-colors" />
+        </div>
+        <div class="flex-1">
+          <label class="block text-xs font-medium text-gray-400 mb-1.5">Display Name</label>
+          <input type="text" name="display_name" placeholder="e.g. Sheet 1 — Overview"
+            class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3 py-2 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent transition-colors" />
+        </div>
+        <button type="submit" class="bg-surface-700 hover:bg-surface-600 border border-gray-700 text-sm text-gray-300 rounded-lg px-4 py-2 transition-colors shrink-0">
+          Attach
+        </button>
+      </form>
+    </div>
+
+    <!-- Share link -->
+    <div class="bg-surface-900 border border-gray-800 rounded-2xl p-6">
+      <h2 class="text-sm font-semibold text-white mb-3">Share Link</h2>
+      <div class="flex items-center gap-3">
+        <input readonly value="<%= typeof baseUrl !== 'undefined' ? baseUrl : '' %>/view/<%= model.slug %>"
+          class="flex-1 bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-gray-400 focus:outline-none" />
+        <button type="button" class="copy-link-btn btn-accent text-white rounded-lg px-4 py-2.5 text-sm font-medium transition-all shrink-0"
+          data-url="<%= typeof baseUrl !== 'undefined' ? baseUrl : '' %>/view/<%= model.slug %>">
+          Copy Link
+        </button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div id="toast" class="fixed bottom-6 right-6 bg-surface-800 border border-gray-700 text-white text-sm px-4 py-3 rounded-xl shadow-2xl opacity-0 translate-y-2 transition-all duration-300 pointer-events-none z-50">
+  <span id="toast-msg"></span>
+</div>
+
+<script src="/admin.js"></script>
+</body>
+</html>

views/admin/login.ejs

@@ -0,0 +1,66 @@
+<%- include('../partials/head', { title: 'Sign In' }) %>
+
+<div class="min-h-screen flex items-center justify-center px-4">
+  <div class="w-full max-w-sm">
+
+    <!-- Logo / Brand -->
+    <div class="text-center mb-8">
+      <% if (brand.brand_logo_path) { %>
+      <img src="/brand/logo" alt="<%= brand.brand_name %>" class="h-12 w-auto mx-auto mb-4 object-contain" />
+      <% } else { %>
+      <div class="inline-flex items-center justify-center w-12 h-12 rounded-xl btn-accent mb-4">
+        <svg class="w-6 h-6 text-white" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25m9-5.25v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />
+        </svg>
+      </div>
+      <% } %>
+      <h1 class="text-xl font-semibold text-white"><%= brand.brand_name %></h1>
+      <p class="text-sm text-gray-500 mt-1">Admin</p>
+    </div>
+
+    <!-- Card -->
+    <div class="bg-surface-900 border border-gray-800 rounded-2xl p-8 shadow-2xl">
+      <h2 class="text-base font-semibold text-white mb-6">Sign in to continue</h2>
+
+      <% if (error) { %>
+      <div class="mb-5 flex items-start gap-3 bg-red-500/10 border border-red-500/30 rounded-lg px-4 py-3">
+        <svg class="w-4 h-4 text-red-400 mt-0.5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z" />
+        </svg>
+        <p class="text-sm text-red-400"><%= error %></p>
+      </div>
+      <% } %>
+
+      <form method="POST" action="/admin/login" class="space-y-4">
+        <input type="hidden" name="next" value="<%= next %>" />
+
+        <div>
+          <label class="block text-xs font-medium text-gray-400 mb-1.5" for="username">Username</label>
+          <input
+            id="username" name="username" type="text"
+            autocomplete="username" required
+            class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent focus:ring-1 ring-accent transition-colors"
+            placeholder="admin"
+          />
+        </div>
+
+        <div>
+          <label class="block text-xs font-medium text-gray-400 mb-1.5" for="password">Password</label>
+          <input
+            id="password" name="password" type="password"
+            autocomplete="current-password" required
+            class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent focus:ring-1 ring-accent transition-colors"
+            placeholder="••••••••"
+          />
+        </div>
+
+        <button type="submit" class="w-full btn-accent text-white rounded-lg px-4 py-2.5 text-sm font-semibold transition-all mt-2">
+          Sign in
+        </button>
+      </form>
+    </div>
+  </div>
+</div>
+
+</body>
+</html>

views/admin/settings.ejs

@@ -0,0 +1,123 @@
+<%- include('../partials/head', { title: 'Settings' }) %>
+<%- include('../partials/adminNav', { currentPath: '/admin/settings' }) %>
+
+<div class="pl-56 min-h-screen">
+  <%- include('../partials/adminBanner') %>
+  <div class="max-w-2xl mx-auto px-8 py-8">
+    <div class="mb-8">
+      <h1 class="text-xl font-semibold text-white">Settings</h1>
+      <p class="text-sm text-gray-500 mt-0.5">Branding, appearance, and app configuration</p>
+    </div>
+
+    <% if (saved) { %>
+    <div class="mb-6 flex items-start gap-3 bg-green-500/10 border border-green-500/30 rounded-lg px-4 py-3">
+      <svg class="w-4 h-4 text-green-400 mt-0.5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+      </svg>
+      <p class="text-sm text-green-400">Settings saved.</p>
+    </div>
+    <% } %>
+
+    <!-- Branding -->
+    <form method="POST" action="/admin/settings" class="bg-surface-900 border border-gray-800 rounded-2xl p-6 mb-6 space-y-5">
+      <h2 class="text-sm font-semibold text-white">Branding</h2>
+
+      <div>
+        <label class="block text-xs font-medium text-gray-400 mb-1.5">App Name</label>
+        <input name="brand_name" type="text" value="<%= settings.brand_name %>"
+          class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white focus:outline-none focus:border-accent transition-colors"
+          placeholder="StepView" />
+        <p class="text-xs text-gray-600 mt-1.5">Shown in the browser tab, viewer overlay, and admin sidebar.</p>
+      </div>
+
+      <div>
+        <label class="block text-xs font-medium text-gray-400 mb-1.5">Tagline</label>
+        <input name="brand_tagline" type="text" value="<%= settings.brand_tagline %>"
+          class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white focus:outline-none focus:border-accent transition-colors"
+          placeholder="3D Model Viewer" />
+      </div>
+
+      <div>
+        <label class="block text-xs font-medium text-gray-400 mb-1.5">Accent Color</label>
+        <div class="flex items-center gap-3">
+          <input type="color" name="brand_accent" value="<%= settings.brand_accent %>"
+            class="h-10 w-16 rounded-lg border border-gray-700 bg-surface-800 cursor-pointer p-1" />
+          <input type="text" id="accent-hex" value="<%= settings.brand_accent %>"
+            class="bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white font-mono w-32 focus:outline-none focus:border-accent transition-colors"
+            placeholder="#3b82f6" />
+        </div>
+        <p class="text-xs text-gray-600 mt-1.5">Used for buttons, highlights, and active nav items.</p>
+      </div>
+
+      <div class="pt-2">
+        <button type="submit" class="btn-accent text-white rounded-lg px-5 py-2 text-sm font-medium transition-all">
+          Save Branding
+        </button>
+      </div>
+    </form>
+
+    <!-- Logo -->
+    <div class="bg-surface-900 border border-gray-800 rounded-2xl p-6 mb-6">
+      <h2 class="text-sm font-semibold text-white mb-4">Logo</h2>
+
+      <% if (settings.brand_logo_path) { %>
+      <div class="flex items-center gap-4 mb-5 p-4 bg-surface-800 rounded-xl border border-gray-700">
+        <img src="/brand/logo" alt="Current logo" class="h-10 w-auto object-contain" />
+        <div class="flex-1">
+          <p class="text-sm text-gray-300">Logo uploaded</p>
+          <p class="text-xs text-gray-500 mt-0.5">PNG, SVG, or JPEG recommended</p>
+        </div>
+        <form method="POST" action="/admin/settings/logo/delete">
+          <button type="submit" class="text-xs text-gray-500 hover:text-red-400 transition-colors">Remove</button>
+        </form>
+      </div>
+      <% } else { %>
+      <p class="text-sm text-gray-500 mb-4">No logo uploaded. A default icon is shown.</p>
+      <% } %>
+
+      <form method="POST" action="/admin/settings/logo" enctype="multipart/form-data" class="flex items-end gap-3">
+        <div class="flex-1">
+          <label class="block text-xs font-medium text-gray-400 mb-1.5">Upload Logo</label>
+          <input type="file" name="logo" accept=".png,.jpg,.jpeg,.svg,.webp" required
+            class="w-full text-sm text-gray-400 file:mr-3 file:py-1.5 file:px-3 file:rounded-lg file:border-0 file:text-xs file:font-medium file:bg-surface-700 file:text-gray-300 hover:file:bg-surface-600 transition-colors" />
+          <p class="text-xs text-gray-600 mt-1">Max 2 MB. PNG or SVG recommended for best quality.</p>
+        </div>
+        <button type="submit" class="bg-surface-700 hover:bg-surface-600 border border-gray-700 text-sm text-gray-300 rounded-lg px-4 py-2 transition-colors shrink-0">
+          Upload
+        </button>
+      </form>
+    </div>
+
+    <!-- Favicon -->
+    <div class="bg-surface-900 border border-gray-800 rounded-2xl p-6">
+      <h2 class="text-sm font-semibold text-white mb-4">Favicon</h2>
+      <form method="POST" action="/admin/settings/favicon" enctype="multipart/form-data" class="flex items-end gap-3">
+        <div class="flex-1">
+          <label class="block text-xs font-medium text-gray-400 mb-1.5">Upload Favicon</label>
+          <input type="file" name="favicon" accept=".ico,.png,.svg" required
+            class="w-full text-sm text-gray-400 file:mr-3 file:py-1.5 file:px-3 file:rounded-lg file:border-0 file:text-xs file:font-medium file:bg-surface-700 file:text-gray-300 hover:file:bg-surface-600 transition-colors" />
+          <p class="text-xs text-gray-600 mt-1">ICO or PNG, max 512 KB. Ideal size: 32×32 px.</p>
+        </div>
+        <button type="submit" class="bg-surface-700 hover:bg-surface-600 border border-gray-700 text-sm text-gray-300 rounded-lg px-4 py-2 transition-colors shrink-0">
+          Upload
+        </button>
+      </form>
+    </div>
+
+  </div>
+</div>
+
+<script>
+  // Keep color picker and hex input in sync
+  const colorInput = document.querySelector('input[type="color"]')
+  const hexInput   = document.getElementById('accent-hex')
+  if (colorInput && hexInput) {
+    colorInput.addEventListener('input', () => { hexInput.value = colorInput.value })
+    hexInput.addEventListener('input', () => {
+      if (/^#[0-9a-fA-F]{6}$/.test(hexInput.value)) colorInput.value = hexInput.value
+    })
+  }
+</script>
+<script src="/admin.js"></script>
+</body>
+</html>

views/admin/upload.ejs

@@ -0,0 +1,93 @@
+<%- include('../partials/head', { title: 'Upload Model' }) %>
+<%- include('../partials/adminNav', { currentPath: '/admin/upload' }) %>
+
+<div class="pl-56 min-h-screen">
+  <%- include('../partials/adminBanner') %>
+  <div class="max-w-2xl mx-auto px-8 py-8">
+    <div class="mb-8">
+      <h1 class="text-xl font-semibold text-white">Upload Model</h1>
+      <p class="text-sm text-gray-500 mt-0.5">Supported formats: STEP, STP, STL</p>
+    </div>
+
+    <% if (error) { %>
+    <div class="mb-6 flex items-start gap-3 bg-red-500/10 border border-red-500/30 rounded-lg px-4 py-3">
+      <svg class="w-4 h-4 text-red-400 mt-0.5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z" />
+      </svg>
+      <p class="text-sm text-red-400"><%= error %></p>
+    </div>
+    <% } %>
+
+    <form method="POST" action="/admin/models" enctype="multipart/form-data" class="space-y-6">
+
+      <!-- Drop zone -->
+      <div id="drop-zone" class="border-2 border-dashed border-gray-700 hover:border-accent rounded-2xl p-12 text-center transition-colors cursor-pointer">
+        <svg class="w-10 h-10 text-gray-600 mx-auto mb-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M3 16.5v2.25A2.25 2.25 0 005.25 21h13.5A2.25 2.25 0 0021 18.75V16.5m-13.5-9L12 3m0 0l4.5 4.5M12 3v13.5" />
+        </svg>
+        <p class="text-sm text-gray-400">Drop a <span class="text-white font-medium">.STEP, .STP, or .STL</span> file here</p>
+        <p class="text-xs text-gray-600 mt-1">or</p>
+        <label class="mt-3 inline-block cursor-pointer">
+          <span class="text-sm text-accent underline">Browse files</span>
+          <input id="model_file" name="model_file" type="file" accept=".step,.stp,.stl" required class="hidden" />
+        </label>
+        <p id="file-name" class="text-xs text-gray-400 mt-3 hidden"></p>
+      </div>
+
+      <!-- Metadata -->
+      <div class="bg-surface-900 border border-gray-800 rounded-2xl p-6 space-y-5">
+        <div>
+          <label class="block text-xs font-medium text-gray-400 mb-1.5" for="name">Display Name <span class="text-red-400">*</span></label>
+          <input id="name" name="name" type="text" required
+            class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent transition-colors"
+            placeholder="e.g. Main Assembly v3"
+          />
+        </div>
+
+        <div>
+          <label class="block text-xs font-medium text-gray-400 mb-1.5" for="description">Description</label>
+          <textarea id="description" name="description" rows="3"
+            class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3.5 py-2.5 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-accent transition-colors resize-none"
+            placeholder="Optional notes about this model…"
+          ></textarea>
+        </div>
+
+        <div class="grid grid-cols-2 gap-4">
+          <div>
+            <label class="block text-xs font-medium text-gray-400 mb-1.5" for="category_id">Category</label>
+            <select id="category_id" name="category_id"
+              class="w-full bg-surface-800 border border-gray-700 rounded-lg px-3 py-2.5 text-sm text-gray-300 focus:outline-none focus:border-accent transition-colors">
+              <option value="">Uncategorized</option>
+              <% categories.forEach(c => { %>
+              <option value="<%= c.id %>"><%= c.name %></option>
+              <% }) %>
+            </select>
+          </div>
+          <div class="flex items-end pb-0.5">
+            <label class="flex items-center gap-2.5 cursor-pointer">
+              <div class="relative">
+                <input id="is_public" name="is_public" type="checkbox" checked class="sr-only peer" />
+                <div class="w-9 h-5 bg-gray-700 rounded-full peer-checked:bg-accent transition-colors"></div>
+                <div class="absolute top-0.5 left-0.5 w-4 h-4 bg-white rounded-full transition-transform peer-checked:translate-x-4"></div>
+              </div>
+              <span class="text-sm text-gray-400">Make public</span>
+            </label>
+          </div>
+        </div>
+      </div>
+
+      <div class="flex gap-3">
+        <button type="submit" class="btn-accent text-white rounded-lg px-6 py-2.5 text-sm font-medium transition-all">
+          Upload Model
+        </button>
+        <a href="/admin" class="bg-surface-800 hover:bg-surface-700 border border-gray-700 text-gray-300 rounded-lg px-6 py-2.5 text-sm font-medium transition-colors">
+          Cancel
+        </a>
+      </div>
+    </form>
+  </div>
+</div>
+
+<script src="/admin.js"></script>
+</body>
+</html>

views/error.ejs

@@ -0,0 +1,12 @@
+<%- include('./partials/head', { title: String(status) }) %>
+
+<div class="min-h-screen flex items-center justify-center px-6">
+  <div class="text-center">
+    <p class="text-6xl font-bold text-gray-800 mb-4"><%= status %></p>
+    <p class="text-base text-gray-400 mb-6"><%= message %></p>
+    <a href="/" class="text-sm text-accent hover:underline">← Go back home</a>
+  </div>
+</div>
+
+</body>
+</html>

views/index.ejs

@@ -0,0 +1,84 @@
+<%- include('./partials/head', { title: 'Models' }) %>
+
+<div class="min-h-screen">
+  <!-- Header -->
+  <header class="border-b border-gray-800 bg-surface-900/80 backdrop-blur-sm sticky top-0 z-10">
+    <div class="max-w-5xl mx-auto px-6 py-4 flex items-center gap-4">
+      <% if (brand.brand_logo_path) { %>
+      <img src="/brand/logo" alt="<%= brand.brand_name %>" class="h-7 w-auto object-contain" />
+      <% } else { %>
+      <div class="h-7 w-7 rounded-md btn-accent flex items-center justify-center shrink-0">
+        <svg class="w-4 h-4 text-white" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25m9-5.25v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />
+        </svg>
+      </div>
+      <% } %>
+      <div>
+        <span class="text-sm font-semibold text-white"><%= brand.brand_name %></span>
+        <% if (brand.brand_tagline) { %>
+        <span class="text-sm text-gray-600 ml-2"><%= brand.brand_tagline %></span>
+        <% } %>
+      </div>
+    </div>
+  </header>
+
+  <main class="max-w-5xl mx-auto px-6 py-10">
+    <% const hasModels = categorised.length > 0 || uncategorized.length > 0 %>
+
+    <% if (!hasModels) { %>
+    <div class="text-center py-24">
+      <svg class="w-14 h-14 text-gray-800 mx-auto mb-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25m9-5.25v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />
+      </svg>
+      <p class="text-gray-600 text-sm">No models are available yet.</p>
+    </div>
+
+    <% } else { %>
+
+    <%
+      // Reusable model card macro (EJS doesn't have macros, so we use a loop target)
+      function modelCard(model) { /* rendered inline below */ }
+    %>
+
+    <!-- Categorised sections -->
+    <% categorised.forEach(({ category, models }) => { %>
+    <section class="mb-12">
+      <div class="flex items-center gap-3 mb-5">
+        <h2 class="text-xs font-semibold text-gray-500 uppercase tracking-wider"><%= category.name %></h2>
+        <div class="flex-1 h-px bg-gray-800"></div>
+        <span class="text-xs text-gray-700"><%= models.length %> model<%= models.length !== 1 ? 's' : '' %></span>
+      </div>
+      <% if (category.description) { %>
+      <p class="text-xs text-gray-600 mb-4 -mt-3"><%= category.description %></p>
+      <% } %>
+      <div class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-4">
+        <% models.forEach(model => { %>
+        <%- include('./partials/modelCard', { model }) %>
+        <% }) %>
+      </div>
+    </section>
+    <% }) %>
+
+    <!-- Uncategorized -->
+    <% if (uncategorized.length > 0) { %>
+    <section>
+      <% if (categorised.length > 0) { %>
+      <div class="flex items-center gap-3 mb-5">
+        <h2 class="text-xs font-semibold text-gray-500 uppercase tracking-wider">Other</h2>
+        <div class="flex-1 h-px bg-gray-800"></div>
+      </div>
+      <% } %>
+      <div class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-4">
+        <% uncategorized.forEach(model => { %>
+        <%- include('./partials/modelCard', { model }) %>
+        <% }) %>
+      </div>
+    </section>
+    <% } %>
+
+    <% } %>
+  </main>
+</div>
+
+</body>
+</html>

views/partials/adminBanner.ejs

@@ -0,0 +1,10 @@
+<% if (typeof defaultPassword !== 'undefined' && defaultPassword) { %>
+<div class="bg-amber-500/10 border-b border-amber-500/20 px-8 py-2.5 flex items-center gap-3">
+  <svg class="w-4 h-4 text-amber-400 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+    <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z" />
+  </svg>
+  <p class="text-xs text-amber-400">
+    You're using the default password. <a href="/admin/settings" class="underline font-medium hover:text-amber-300">Change it now</a> before exposing this app to a network.
+  </p>
+</div>
+<% } %>

views/partials/adminNav.ejs

@@ -0,0 +1,59 @@
+<aside class="fixed inset-y-0 left-0 w-56 bg-surface-900 border-r border-gray-800 flex flex-col z-20">
+  <!-- Brand -->
+  <div class="flex items-center gap-3 px-5 py-5 border-b border-gray-800">
+    <% if (brand.brand_logo_path) { %>
+    <img src="/brand/logo" alt="<%= brand.brand_name %>" class="h-7 w-auto object-contain" />
+    <% } else { %>
+    <div class="h-7 w-7 rounded-md btn-accent flex items-center justify-center shrink-0">
+      <svg class="w-4 h-4 text-white" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25m9-5.25v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />
+      </svg>
+    </div>
+    <% } %>
+    <div class="overflow-hidden">
+      <p class="text-sm font-semibold text-white truncate"><%= brand.brand_name %></p>
+      <p class="text-xs text-gray-500 truncate">Admin</p>
+    </div>
+  </div>
+
+  <!-- Nav links -->
+  <nav class="flex-1 py-4 px-3 space-y-1 overflow-y-auto">
+    <%
+      const navItems = [
+        { href: '/admin',            label: 'Models',     icon: 'cube' },
+        { href: '/admin/upload',     label: 'Upload',     icon: 'upload' },
+        { href: '/admin/categories', label: 'Categories', icon: 'folder' },
+        { href: '/admin/settings',   label: 'Settings',   icon: 'settings' },
+      ]
+      const icons = {
+        cube:     '<path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25m9-5.25v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />',
+        upload:   '<path stroke-linecap="round" stroke-linejoin="round" d="M3 16.5v2.25A2.25 2.25 0 005.25 21h13.5A2.25 2.25 0 0021 18.75V16.5m-13.5-9L12 3m0 0l4.5 4.5M12 3v13.5" />',
+        folder:   '<path stroke-linecap="round" stroke-linejoin="round" d="M2.25 12.75V12A2.25 2.25 0 014.5 9.75h15A2.25 2.25 0 0121.75 12v.75m-8.69-6.44l-2.12-2.12a1.5 1.5 0 00-1.061-.44H4.5A2.25 2.25 0 002.25 6v12a2.25 2.25 0 002.25 2.25h15A2.25 2.25 0 0021.75 18V9a2.25 2.25 0 00-2.25-2.25h-5.379a1.5 1.5 0 01-1.06-.44z" />',
+        settings: '<path stroke-linecap="round" stroke-linejoin="round" d="M9.594 3.94c.09-.542.56-.94 1.11-.94h2.593c.55 0 1.02.398 1.11.94l.213 1.281c.063.374.313.686.645.87.074.04.147.083.22.127.325.196.72.257 1.075.124l1.217-.456a1.125 1.125 0 011.37.49l1.296 2.247a1.125 1.125 0 01-.26 1.431l-1.003.827c-.293.241-.438.613-.43.992a7.723 7.723 0 010 .255c-.008.378.137.75.43.991l1.004.827c.424.35.534.955.26 1.43l-1.298 2.247a1.125 1.125 0 01-1.369.491l-1.217-.456c-.355-.133-.75-.072-1.076.124a6.47 6.47 0 01-.22.128c-.331.183-.581.495-.644.869l-.213 1.281c-.09.543-.56.94-1.11.94h-2.594c-.55 0-1.019-.398-1.11-.94l-.213-1.281c-.062-.374-.312-.686-.644-.87a6.52 6.52 0 01-.22-.127c-.325-.196-.72-.257-1.076-.124l-1.217.456a1.125 1.125 0 01-1.369-.49l-1.297-2.247a1.125 1.125 0 01.26-1.431l1.004-.827c.292-.24.437-.613.43-.991a6.932 6.932 0 010-.255c.007-.38-.138-.751-.43-.992l-1.004-.827a1.125 1.125 0 01-.26-1.43l1.297-2.247a1.125 1.125 0 011.37-.491l1.216.456c.356.133.751.072 1.076-.124.072-.044.146-.086.22-.128.332-.183.582-.495.644-.869l.214-1.28z" /><path stroke-linecap="round" stroke-linejoin="round" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />',
+      }
+    %>
+    <% navItems.forEach(item => {
+      const active = currentPath && (currentPath === item.href || (item.href !== '/admin' && currentPath.startsWith(item.href)))
+    %>
+    <a href="<%= item.href %>"
+       class="flex items-center gap-3 px-3 py-2 rounded-lg text-sm transition-colors <%= active ? 'btn-accent text-white font-medium' : 'text-gray-400 hover:text-white hover:bg-surface-800' %>">
+      <svg class="w-4 h-4 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+        <%- icons[item.icon] %>
+      </svg>
+      <%= item.label %>
+    </a>
+    <% }) %>
+  </nav>
+
+  <!-- Logout -->
+  <div class="p-3 border-t border-gray-800">
+    <form method="POST" action="/admin/logout">
+      <button type="submit" class="w-full flex items-center gap-3 px-3 py-2 rounded-lg text-sm text-gray-400 hover:text-white hover:bg-surface-800 transition-colors">
+        <svg class="w-4 h-4 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M15.75 9V5.25A2.25 2.25 0 0013.5 3h-6a2.25 2.25 0 00-2.25 2.25v13.5A2.25 2.25 0 007.5 21h6a2.25 2.25 0 002.25-2.25V15M12 9l-3 3m0 0l3 3m-3-3h12.75" />
+        </svg>
+        Sign out
+      </button>
+    </form>
+  </div>
+</aside>

views/partials/head.ejs

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en" class="dark">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title><%= typeof title !== 'undefined' ? title + ' — ' : '' %><%= brand.brand_name %></title>
+
+  <% if (brand.brand_favicon_path) { %>
+  <link rel="icon" href="/brand/favicon" />
+  <% } %>
+
+  <!-- Inter font -->
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
+
+  <link rel="stylesheet" href="/style.css" />
+
+  <!-- Dynamic brand accent color -->
+  <style>
+    :root { --accent: <%= brand.brand_accent %>; }
+    .btn-accent          { background-color: var(--accent); }
+    .btn-accent:hover    { filter: brightness(1.12); }
+    .border-accent       { border-color: var(--accent); }
+    .text-accent         { color: var(--accent); }
+    .ring-accent:focus   { --tw-ring-color: var(--accent); }
+  </style>
+</head>
+<body class="bg-surface-950 text-gray-100 font-sans antialiased min-h-screen">

views/partials/modelCard.ejs

@@ -0,0 +1,31 @@
+<a href="/view/<%= model.slug %>"
+   class="group bg-surface-900 border border-gray-800 hover:border-gray-600 rounded-2xl overflow-hidden transition-all duration-200 hover:shadow-2xl hover:shadow-black/30 hover:-translate-y-0.5 flex flex-col">
+
+  <!-- Thumbnail / placeholder -->
+  <div class="aspect-video bg-surface-800 flex items-center justify-center overflow-hidden">
+    <% if (model.thumbnail_path) { %>
+    <img src="/files/thumbnail/<%= model.id %>"
+         alt="<%= model.name %>"
+         class="w-full h-full object-cover group-hover:scale-105 transition-transform duration-300" />
+    <% } else { %>
+    <svg class="w-10 h-10 text-gray-700 group-hover:text-gray-600 transition-colors" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25m9-5.25v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />
+    </svg>
+    <% } %>
+  </div>
+
+  <!-- Info -->
+  <div class="p-4 flex-1 flex flex-col gap-1">
+    <p class="text-sm font-medium text-white group-hover:text-accent transition-colors leading-snug">
+      <%= model.name %>
+    </p>
+    <% if (model.description) { %>
+    <p class="text-xs text-gray-500 line-clamp-2 leading-relaxed"><%= model.description %></p>
+    <% } %>
+    <div class="flex items-center gap-2 mt-auto pt-2">
+      <span class="text-xs font-mono bg-surface-800 border border-gray-700 text-gray-500 px-1.5 py-0.5 rounded">
+        <%= model.file_type.toUpperCase() %>
+      </span>
+    </div>
+  </div>
+</a>

views/viewer.ejs

@@ -0,0 +1,152 @@
+<%- include('./partials/head', { title: model.name }) %>
+
+<style>
+  body { overflow: hidden; }
+  #viewer-canvas { display: block; width: 100vw; height: 100vh; }
+  #pdf-panel { transition: transform 0.3s ease; }
+  #pdf-panel.closed { transform: translateX(100%); }
+</style>
+
+<!-- 3D Canvas -->
+<canvas id="viewer-canvas"></canvas>
+
+<!-- Loading overlay -->
+<div id="loading-overlay" class="fixed inset-0 bg-surface-950 flex items-center justify-center z-30">
+  <div class="text-center">
+    <div class="w-10 h-10 border-2 border-accent border-t-transparent rounded-full animate-spin mx-auto mb-4"></div>
+    <p class="text-sm text-gray-400" id="loading-msg">Loading model…</p>
+  </div>
+</div>
+
+<!-- Error overlay -->
+<div id="error-overlay" class="fixed inset-0 bg-surface-950 items-center justify-center z-30 hidden">
+  <div class="text-center max-w-sm px-6">
+    <svg class="w-12 h-12 text-red-400 mx-auto mb-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z" />
+    </svg>
+    <p class="text-sm text-gray-300 font-medium mb-2">Failed to load model</p>
+    <p id="error-msg" class="text-xs text-gray-500"></p>
+  </div>
+</div>
+
+<!-- Top-right controls -->
+<div class="fixed top-5 right-5 flex items-center gap-2 z-20">
+
+  <!-- Wireframe toggle -->
+  <button id="wireframe-btn" title="Toggle wireframe"
+    class="flex items-center justify-center w-8 h-8 bg-surface-900/90 backdrop-blur-sm border border-gray-700 hover:border-gray-600 text-gray-400 hover:text-white rounded-xl transition-all">
+    <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25m9-5.25v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />
+    </svg>
+  </button>
+
+  <!-- Reset camera -->
+  <button id="reset-camera-btn" title="Reset camera"
+    class="flex items-center justify-center w-8 h-8 bg-surface-900/90 backdrop-blur-sm border border-gray-700 hover:border-gray-600 text-gray-400 hover:text-white rounded-xl transition-all">
+    <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.75">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0l3.181 3.183a8.25 8.25 0 0013.803-3.7M4.031 9.865a8.25 8.25 0 0113.803-3.7l3.181 3.182m0-4.991v4.99" />
+    </svg>
+  </button>
+
+  <!-- Copy link -->
+  <button id="copy-link-btn"
+    data-url="<%= shareUrl %>"
+    class="flex items-center gap-2 bg-surface-900/90 backdrop-blur-sm border border-gray-700 hover:border-gray-600 text-gray-300 hover:text-white rounded-xl px-3.5 py-2 text-xs font-medium transition-all">
+    <svg class="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M13.19 8.688a4.5 4.5 0 011.242 7.244l-4.5 4.5a4.5 4.5 0 01-6.364-6.364l1.757-1.757m13.35-.622l1.757-1.757a4.5 4.5 0 00-6.364-6.364l-4.5 4.5a4.5 4.5 0 001.242 7.244" />
+    </svg>
+    Copy Link
+  </button>
+
+  <!-- PDF toggle (only shown if PDFs exist) -->
+  <% if (pdfs.length > 0) { %>
+  <button id="pdf-toggle-btn"
+    class="flex items-center gap-2 bg-surface-900/90 backdrop-blur-sm border border-gray-700 hover:border-gray-600 text-gray-300 hover:text-white rounded-xl px-3.5 py-2 text-xs font-medium transition-all">
+    <svg class="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z" />
+    </svg>
+    Diagrams <span class="opacity-60">(<%= pdfs.length %>)</span>
+  </button>
+  <% } %>
+</div>
+
+<!-- Bottom-left model info -->
+<div class="fixed bottom-6 left-6 z-20 max-w-xs">
+  <% if (brand.brand_logo_path) { %>
+  <img src="/brand/logo" alt="<%= brand.brand_name %>" class="h-5 w-auto object-contain mb-3 opacity-70" />
+  <% } %>
+  <h1 class="text-base font-semibold text-white leading-tight"><%= model.name %></h1>
+  <% if (model.category_name) { %>
+  <p class="text-xs text-gray-500 mt-0.5"><%= model.category_name %></p>
+  <% } %>
+  <% if (model.description) { %>
+  <p class="text-xs text-gray-400 mt-1.5 leading-relaxed"><%= model.description %></p>
+  <% } %>
+</div>
+
+<!-- Bottom-right orbit hint -->
+<div class="fixed bottom-6 right-6 z-20 text-right hidden md:block">
+  <p class="text-xs text-gray-700">Left drag — rotate &nbsp;·&nbsp; Right drag — pan &nbsp;·&nbsp; Scroll — zoom</p>
+</div>
+
+<!-- PDF slide-in panel -->
+<% if (pdfs.length > 0) { %>
+<div id="pdf-panel" class="fixed top-0 right-0 h-full w-full max-w-md bg-surface-900 border-l border-gray-800 z-20 closed flex flex-col">
+  <!-- Panel header -->
+  <div class="flex items-center justify-between px-5 py-4 border-b border-gray-800 shrink-0">
+    <div>
+      <h2 class="text-sm font-semibold text-white">Shop Diagrams</h2>
+      <p class="text-xs text-gray-500 mt-0.5"><%= model.name %></p>
+    </div>
+    <button id="pdf-close-btn" class="p-1.5 rounded-lg text-gray-500 hover:text-white hover:bg-surface-800 transition-colors">
+      <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" />
+      </svg>
+    </button>
+  </div>
+
+  <!-- PDF tabs -->
+  <% if (pdfs.length > 1) { %>
+  <div class="flex border-b border-gray-800 overflow-x-auto shrink-0">
+    <% pdfs.forEach((pdf, i) => { %>
+    <button
+      class="pdf-tab px-4 py-2.5 text-xs whitespace-nowrap font-medium transition-colors border-b-2 <%= i === 0 ? 'border-accent text-white' : 'border-transparent text-gray-500 hover:text-gray-300' %>"
+      data-tab="<%= i %>">
+      <%= pdf.display_name %>
+    </button>
+    <% }) %>
+  </div>
+  <% } %>
+
+  <!-- PDF viewer -->
+  <div class="flex-1 overflow-hidden relative">
+    <% pdfs.forEach((pdf, i) => { %>
+    <iframe
+      src="/files/pdf/<%= model.id %>/<%= pdf.id %>#toolbar=0&navpanes=0&view=FitH"
+      class="pdf-frame absolute inset-0 w-full h-full border-0 <%= i > 0 ? 'hidden' : '' %>"
+      data-frame="<%= i %>"
+    ></iframe>
+    <% }) %>
+  </div>
+</div>
+<% } %>
+
+<!-- Toast -->
+<div id="toast" class="fixed bottom-6 left-1/2 -translate-x-1/2 bg-surface-800 border border-gray-700 text-white text-sm px-4 py-3 rounded-xl shadow-2xl opacity-0 transition-all duration-300 pointer-events-none z-50">
+  <span id="toast-msg"></span>
+</div>
+
+<!-- Model data passed to viewer JS -->
+<script>
+  window.__STEPVIEW__ = {
+    modelId:     <%= model.id %>,
+    fileType:    '<%= model.file_type %>',
+    shareUrl:    '<%- shareUrl %>',
+    hasPdfs:     <%= pdfs.length > 0 %>,
+    hasGeometry: <%= typeof hasGeometry !== 'undefined' ? hasGeometry : false %>,
+  }
+</script>
+
+<script src="/viewer.js"></script>
+</body>
+</html>

vite.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'vite'
+import { resolve } from 'path'
+
+export default defineConfig({
+  build: {
+    outDir: 'public',
+    emptyOutDir: true,
+    rollupOptions: {
+      input: {
+        admin: resolve(__dirname, 'src/client/admin/main.ts'),
+        viewer: resolve(__dirname, 'src/client/viewer/main.ts'),
+      },
+      // occt-import-js is an optional Phase 3 dep; skip it at build time
+      external: ['occt-import-js'],
+      output: {
+        entryFileNames: '[name].js',
+        chunkFileNames: '[name]-[hash].js',
+        assetFileNames: '[name][extname]',
+      },
+    },
+  },
+  css: {
+    postcss: './postcss.config.cjs',
+  },
+  resolve: {
+    alias: {
+      '@client': resolve(__dirname, 'src/client'),
+    },
+  },
+})