Merge pull request #4 from AnExiledDev/docs/feedback-updates

Docs: trim First Session, expand Installation troubleshooting

Author: AnExiledDev

.devcontainer/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [v1.14.2] - 2026-02-24
 
+### Changed
+
+#### Docs
+- **First Session page** — trimmed from 198 to 128 lines by consolidating "What Happens Automatically" into a concise summary, replacing full agent/skill tables with brief teasers linking to their dedicated pages
+- **Installation Troubleshooting** — expanded from 4 to 10 FAQ entries covering `npx` failures, VS Code extension issues, Docker permissions on Linux, WSL 2 integration, port conflicts, and slow rebuilds
+
 ### Fixed
 
 #### CI: Release Workflow (v1.14.1)
@@ -18,6 +24,7 @@
 
 #### Docs
 - **Active sidebar item** — increased background opacity from 0.08 to 0.14, added `font-weight: 600` and `color: var(--sl-color-accent-high)` for readable contrast against inactive items
+- **Stale skill counts** — 5 pages (First Session, Getting Started index, Features index) referenced "21 skills" instead of the correct total of 34 across all plugins (skill-engine: 21, spec-workflow: 8, ticket-workflow: 4, agent-system: 1)
 
 ## [v1.14.0] - 2026-02-24
 

docs/src/content/docs/features/index.md

@@ -14,7 +14,7 @@ This section is your reference guide to everything CodeForge provides. Whether y
 Out of the box, CodeForge gives you:
 
 - **17 specialized AI agents** with focused expertise and safety-calibrated tool access
-- **21 domain knowledge packs** (skills) for frameworks, patterns, and workflows
+- **34 domain knowledge packs** (skills) for frameworks, patterns, and workflows
 - **21 CLI tools** for session management, code quality, and development
 - **3 layers of code intelligence** — AST-based search, syntax parsing, and LSP semantic analysis
 - **12 plugins** that wire everything together with hooks, guards, and automation
@@ -43,7 +43,7 @@ Key safety features set CodeForge agents apart:
 
 ## Skills
 
-**21 domain-specific knowledge packs** give Claude deep expertise in frameworks, patterns, and workflows. When you start discussing FastAPI routes or Svelte 5 runes, the skill engine detects the context and auto-suggests the relevant skill. Once loaded, the skill injects structured knowledge — best practices, code patterns, API references, and common pitfalls — directly into Claude's context for the current task.
+**34 domain-specific knowledge packs** give Claude deep expertise in frameworks, patterns, and workflows. The skill engine provides 21 core skills covering frameworks, practices, and Claude/CodeForge topics. Additional skills come from the spec-workflow (8), ticket-workflow (4), and agent-system (1) plugins. When you start discussing FastAPI routes or Svelte 5 runes, the skill engine detects the context and auto-suggests the relevant skill. Once loaded, the skill injects structured knowledge — best practices, code patterns, API references, and common pitfalls — directly into Claude's context for the current task.
 
 Each skill is built around a "mental model" — a concise explanation of how a technology works, followed by concrete patterns, code examples, and guidance. This is not generic documentation; skills encode the kind of working knowledge a senior specialist carries.
 
@@ -55,7 +55,7 @@ Skills cover three categories:
 | **Practices** | Testing, Debugging, Security, Refactoring, API Design | Methodology, checklists, and established patterns |
 | **Claude & CodeForge** | Agent SDK, Headless Mode, Skill Building, Spec Writing | Guidance for building on and extending CodeForge itself |
 
-[View all 21 skills →](./skills/)
+[View all 34 skills →](./skills/)
 
 ## CLI Tools
 
@@ -90,7 +90,7 @@ CodeForge installs LSP servers for Python (Pyright), TypeScript/JavaScript, and
 | Category | Count | Highlights |
 |----------|-------|------------|
 | [Agents](./agents/) | 17 | Architect, Explorer, Security Auditor, Test Writer, Refactorer, and 12 more |
-| [Skills](./skills/) | 21 | FastAPI, Svelte 5, Docker, Testing, Debugging, Security, and 15 more |
+| [Skills](./skills/) | 34 | FastAPI, Svelte 5, Docker, Testing, Debugging, Security, and 28 more |
 | [CLI Tools](./tools/) | 21 | Session search, token tracking, code quality, formatters, and runtimes |
 | [Code Intelligence](./code-intelligence/) | 3 | ast-grep, tree-sitter, LSP servers for Python/TS/Go |
 

docs/src/content/docs/getting-started/first-session.md

@@ -32,39 +32,11 @@ If something isn't working as expected in a CodeForge session, try `ccraw` to se
 
 ## What Happens Automatically
 
-When your session starts, several systems activate behind the scenes to make Claude smarter and safer. You don't need to configure any of this — it just works.
+When your session starts, several systems activate behind the scenes. You don't need to configure any of this — it just works.
 
-### System Prompt Loading
-
-The main system prompt gives Claude context about your project, coding standards, and behavioral guidelines. It's loaded from your configuration directory and defines how Claude approaches tasks, what tools to prefer, and how to communicate. The prompt is customizable — see [System Prompts](../customization/system-prompts/) for details.
-
-### Plugin Hook Activation
-
-Plugins register hooks that fire at specific points during your session. These run automatically and silently in the background:
-
-**PreToolUse hooks** run before Claude executes a command or edits a file:
-- The **workspace scope guard** blocks writes outside your project directory
-- The **dangerous command blocker** catches destructive shell commands (`rm -rf /`, `git push --force`, etc.)
-- The **protected files guard** prevents edits to secrets, lock files, and other sensitive files
-
-**PostToolUse hooks** run after a tool completes:
-- The **session context** plugin injects git state and TODO information
-- The **notify hook** sends a desktop notification when Claude finishes a long task
-
-**Stop hooks** run when Claude finishes a turn:
-- The **spec reminder** checks whether code was modified without updating specs
-- The **auto code quality** plugin runs formatting and linting checks
-- The **commit reminder** nudges you to commit if there are significant uncommitted changes
-
-### Session Context Injection
-
-The session context plugin keeps Claude informed about your working environment. At turn boundaries, it injects:
-
-- **Git state** — current branch, uncommitted changes, recent commits
-- **Active TODOs** — extracted from TODO comments in recently modified files
-- **Commit reminders** — when there are significant uncommitted changes
-
-This means Claude always knows the state of your repository without you having to explain it.
+- **System prompt** — gives Claude context about your project, coding standards, and how to communicate. Customizable via [System Prompts](../customization/system-prompts/).
+- **Plugin hooks** — 12 plugins fire automatically at key moments: blocking dangerous commands, guarding workspace scope, injecting git state, running code quality checks, and more. See the [Plugins Overview](../plugins/) for details on each one.
+- **Session context** — Claude always knows your current branch, uncommitted changes, recent commits, and active TODOs without you having to explain it.
 
 ## What to Try First
 
@@ -122,53 +94,12 @@ ccusage
 claude-dashboard
 ```
 
-## Working with Agents
-
-CodeForge includes 17 specialized agents. You don't need to know their names — Claude automatically delegates to the right agent based on your request. But understanding what's available helps you make better requests.
-
-Here are some example interactions and which agents handle them:
-
-| Your Request | Agent | What It Does |
-|-------------|-------|-------------|
-| "Explore this codebase" | Explorer | Systematic codebase navigation |
-| "Design the API for user management" | Architect | System design and architecture |
-| "Debug why the login fails" | Debug Logs | Log analysis and bug investigation |
-| "Refactor this module to reduce duplication" | Refactorer | Safe, incremental code transformations |
-| "Write a migration from SQLite to PostgreSQL" | Migrator | Database and framework migrations |
-| "Profile the performance of the search endpoint" | Perf Profiler | Performance analysis and optimization |
-| "Audit this module for vulnerabilities" | Security Auditor | Security review and recommendations |
-| "Write documentation for the API" | Doc Writer | Documentation generation |
-
-Each agent carries domain-specific instructions that guide how Claude approaches the task. For example, the security auditor checks OWASP Top 10 categories, while the test writer respects your project's testing patterns and frameworks.
-
-See [Agents](../features/agents/) for the full list of all 17 agents and their specializations.
-
-## Working with Skills
-
-Skills are domain-specific knowledge packs that Claude draws on when relevant. They're suggested automatically by the skill engine based on what you're working on, or you can invoke them directly with slash commands.
-
-### Frequently Used Skills
-
-| Skill | What It Provides |
-|-------|-----------------|
-| `/spec-new` | Create a new feature specification |
-| `/spec-build` | Implement a feature from its spec (plan, build, review, close) |
-| `/spec-check` | Audit spec health across the project |
-| `/spec-update` | Update specs to match current implementation |
-
-### Auto-Suggested Skills
-
-You don't always need to invoke skills manually. The skill engine watches what you're working on and suggests relevant skills. For example:
-
-- Working on a FastAPI endpoint? The FastAPI skill is suggested with best practices for route design, dependency injection, and error handling
-- Writing Docker configuration? The Docker skill provides patterns for multi-stage builds, security hardening, and compose setups
-- Debugging a tricky issue? The debugging skill offers systematic approaches to isolate and fix problems
-
-See [Skills](../features/skills/) for the complete catalog of all 21 available skills.
+## Agents and Skills
 
-## Understanding the Status Line
+CodeForge includes **17 specialized agents** and **34 skills** that activate automatically based on what you're working on. You don't need to memorize names — just describe what you want, and Claude delegates to the right specialist. The examples in "What to Try First" above show this in action.
 
-If your terminal supports it, CodeForge provides a status line that shows session information at a glance. The `ccstatusline` feature adds session metadata to your terminal prompt, so you always know which session you're in and its current state.
+- **[Agents](../features/agents/)** — specialized AI personas for architecture, debugging, testing, security, migrations, and more
+- **[Skills](../features/skills/)** — domain-specific knowledge packs (FastAPI, Docker, Svelte, debugging patterns, etc.) that the skill engine suggests automatically or you invoke with slash commands like `/spec-new`
 
 ## Tips for Effective Sessions
 

docs/src/content/docs/getting-started/index.md

@@ -5,7 +5,7 @@ sidebar:
   order: 1
 ---
 
-CodeForge is a DevContainer configuration that transforms your development environment into an AI-powered workspace. It bundles 12 plugins, 21 tools, 17 specialized agents, and 21 skills into a single `npx codeforge-dev` install.
+CodeForge is a DevContainer configuration that transforms your development environment into an AI-powered workspace. It bundles 12 plugins, 21 tools, 17 specialized agents, and 34 skills into a single `npx codeforge-dev` install.
 
 ## What is CodeForge?
 
@@ -75,7 +75,7 @@ Agents are specialized AI personas that Claude delegates to based on your reques
 
 See [Agents](../features/agents/) for the full roster.
 
-### 21 Skills
+### 34 Skills
 
 Skills are domain-specific knowledge packs that Claude can draw on. They provide curated best practices, patterns, and workflows for specific technologies and tasks:
 

docs/src/content/docs/getting-started/installation.md

@@ -206,6 +206,53 @@ Use `git diff .devcontainer/` after updating to review what changed before commi
 - If starts are consistently slow, check Docker resource allocation
 - The `postStartCommand` runs on every start to deploy configuration files — this is normal and should complete in a few seconds
 
+### `npx codeforge-dev` fails
+
+**Symptoms:** The installer command errors out before creating `.devcontainer/`.
+
+- **Node.js not installed** — the installer requires Node.js 18+ and npm. Run `node --version` to check; install from [nodejs.org](https://nodejs.org/) if missing
+- **Network issues** — npm needs to reach the registry to download the package. Check your connection or try `npm config set registry https://registry.npmjs.org/`
+- **Permission errors** — on some systems, global npm installs need `sudo`. Try `npx --yes codeforge-dev` or install globally with `sudo npm install -g codeforge-dev`
+
+### VS Code doesn't show "Reopen in Container"
+
+**Symptoms:** You opened the project in VS Code but never see the DevContainer prompt.
+
+- **Extension not installed** — install `ms-vscode-remote.remote-containers` from the Extensions marketplace, then reload VS Code
+- **`.devcontainer/` not at repo root** — VS Code looks for `.devcontainer/` in the workspace root folder. If your project is inside a subfolder, open that subfolder directly
+- **VS Code version** — DevContainers requires VS Code 1.85 or later. Check **Help → About** and update if needed
+
+### Docker permission errors (Linux)
+
+**Symptoms:** `docker: permission denied` or `Cannot connect to the Docker daemon` errors.
+
+- Add your user to the `docker` group: `sudo usermod -aG docker $USER`, then log out and back in
+- Verify with `docker ps` — it should run without `sudo`
+- If using Docker rootless mode, ensure the socket path is set correctly in VS Code settings
+
+### WSL 2 integration issues (Windows)
+
+**Symptoms:** Container fails to start, or Docker commands hang inside WSL.
+
+- Open Docker Desktop → **Settings → Resources → WSL Integration** and enable integration for your WSL distro
+- Ensure WSL 2 (not WSL 1) is active: run `wsl -l -v` in PowerShell and check the VERSION column
+- Restart Docker Desktop after changing WSL settings
+
+### Port conflicts
+
+**Symptoms:** The claude-dashboard or other tools fail to bind their port.
+
+- CodeForge's session dashboard uses **port 7847** by default. If another service uses that port, change it in `devcontainer.json` under `forwardPorts`
+- To find what's using a port: `lsof -i :7847` (macOS/Linux) or `netstat -ano | findstr 7847` (Windows)
+
+### Container rebuilds are slow
+
+**Symptoms:** Rebuilding the container takes as long as the first build.
+
+- **Use "Rebuild Container"** (not "Rebuild Without Cache") for routine rebuilds — Docker reuses cached layers for unchanged steps
+- **Prune unused images** to free disk space: `docker system prune -a` removes all unused images (confirm you don't need them first)
+- **Check disk space** — Docker needs headroom for layer storage. If your disk is nearly full, builds may fail or slow down significantly
+
 ## Next Steps
 
 - [First Session](./first-session/) — start using CodeForge with Claude Code

docs/src/content/docs/reference/changelog.md

@@ -51,6 +51,12 @@ For minor and patch updates, you can usually just rebuild the container. Check t
 
 **Release date:** 2026-02-24
 
+### Changed
+
+#### Docs
+- **First Session page** — trimmed from 198 to 128 lines by consolidating "What Happens Automatically" into a concise summary, replacing full agent/skill tables with brief teasers linking to their dedicated pages
+- **Installation Troubleshooting** — expanded from 4 to 10 FAQ entries covering `npx` failures, VS Code extension issues, Docker permissions on Linux, WSL 2 integration, port conflicts, and slow rebuilds
+
 ### Fixed
 
 #### CI: Release Workflow (v1.14.1)
@@ -67,6 +73,7 @@ For minor and patch updates, you can usually just rebuild the container. Check t
 
 #### Docs
 - **Active sidebar item** — increased background opacity from 0.08 to 0.14, added `font-weight: 600` and `color: var(--sl-color-accent-high)` for readable contrast against inactive items
+- **Stale skill counts** — 5 pages (First Session, Getting Started index, Features index) referenced "21 skills" instead of the correct total of 34 across all plugins (skill-engine: 21, spec-workflow: 8, ticket-workflow: 4, agent-system: 1)
 
 ## v1.14.0