Fix documentation inaccuracies and reduce duplication

README.md

@@ -258,26 +258,17 @@ The tool assembles the context in the following order:
 
 ### File Search Paths
 
-The tool looks for task and rule files in the following locations, in order of precedence:
+The tool automatically searches for task and rule files in various locations. For a complete reference, see the [Search Paths documentation](https://kitproj.github.io/coding-context-cli/reference/search-paths).
 
-**Tasks:**
-- `./.agents/tasks/*.md` (task name matches filename without `.md` extension)
+**Common locations:**
+- `./.agents/tasks/*.md` - Task definitions
+- `./.agents/rules/` - Rule files  
+- `./.agents/commands/` - Reusable command blocks
+- `./.agents/skills/*/SKILL.md` - Specialized skills
+- Various agent-specific paths (`.cursor/`, `.github/`, `.opencode/`, etc.)
+- User-wide rules in `~/.agents/rules`, `~/.claude/`, `~/.codex/`, etc.
 
-**Commands** (reusable content blocks referenced via slash commands like `/command-name` inside task content):
-- `./.agents/commands/*.md`
-- `./.cursor/commands/*.md`
-- `./.opencode/command/*.md`
-
-**Skills** (specialized capabilities with progressive disclosure):
-- `./.agents/skills/*/SKILL.md` (each subdirectory in `.agents/skills/` can contain a `SKILL.md` file)
-
-**Rules:**
-The tool searches for a variety of files and directories, including:
-- `CLAUDE.local.md`
-- `.agents/rules`, `.cursor/rules`, `.augment/rules`, `.windsurf/rules`, `.opencode/agent`
-- `.github/copilot-instructions.md`, `.github/agents`, `.gemini/styleguide.md`, `.augment/guidelines.md`
-- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`
-- User-specific rules in `~/.agents/rules`, `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.opencode/rules`, etc.
+See the full [Search Paths Reference](https://kitproj.github.io/coding-context-cli/reference/search-paths) for the complete list of locations.
 
 ### Remote File System Support
 
@@ -827,3 +818,35 @@ Perfect for:
 - **Tech talks** - Present at meetups or conferences
 - **Workshops** - Run hands-on training sessions
 - **Documentation** - Visual reference for features
+
+## Troubleshooting
+
+### Common Issues
+
+**Task not found**
+- Verify the task file exists in `.agents/tasks/` with the correct filename
+- Tasks are matched by filename (without `.md` extension), not by `task_name` in frontmatter
+- Check that you're using the correct task name: `coding-context fix-bug` (not `/fix-bug`)
+
+**No rules included**
+- Check that rule files exist in search paths (`.agents/rules/`, etc.)
+- Verify selector syntax: use `-s languages=go` (not `-p languages=go`)
+- Remember: `-s` filters rules, `-p` substitutes parameters
+- Rules without frontmatter are always included (unless using resume mode)
+
+**Parameters not substituted**
+- Ensure you're using `-p` flag: `coding-context -p issue=123 fix-bug`
+- Check parameter names match exactly (case-sensitive): `${issue_key}` matches `-p issue_key=...`
+- Verify the task file uses `${parameter}` syntax
+
+**Wrong rules included**
+- Check frontmatter spelling and case sensitivity
+- Use `languages:` (plural) in frontmatter and `-s languages=go` in selectors
+- All selectors must match (AND logic): `-s languages=go -s stage=testing`
+
+**Bootstrap script not running**
+- Make the script executable: `chmod +x .agents/rules/my-rule-bootstrap`
+- Name it correctly: `{rule-filename}-bootstrap` (e.g., `jira-context-bootstrap` for `jira-context.md`)
+- Check script output in stderr
+
+For more help, see the [full documentation](https://kitproj.github.io/coding-context-cli/) or [open an issue](https://github.com/kitproj/coding-context-cli/issues).

SPECIFICATION.md

@@ -766,15 +766,15 @@ Selectors filter rules and tasks based on frontmatter metadata, enabling context
 **Command-line:**
 ```bash
 -s key=value
--s language=go
+-s languages=go
 -s stage=implementation
 ```
 
 **Task frontmatter:**
 ```yaml
 ---
 selectors:
-  language: go
+  languages: go
   stage: implementation
 ---
 ```
@@ -785,10 +785,11 @@ selectors:
 ```yaml
 # Rule frontmatter
 ---
-language: go
+languages:
+  - go
 ---
 
-# Selector: -s language=go
+# Selector: -s languages=go
 # Result: ✅ Match
 ```
 
@@ -810,8 +811,8 @@ languages:
 
 **Multiple selectors (AND logic):**
 ```bash
-# Requires: language=go AND stage=implementation
--s language=go -s stage=implementation
+# Requires: languages=go AND stage=implementation
+-s languages=go -s stage=implementation
 ```
 
 **OR logic (task frontmatter):**

docs/how-to/create-rules.md

@@ -192,7 +192,7 @@ coding-context -s source=jira fix-bug
 
 ## Common Language Values
 
-Use lowercase values in your `language:` frontmatter:
+Use lowercase values in your `languages:` frontmatter:
 
 - c, c++, c#, css
 - dart, elixir, go

docs/how-to/create-tasks.md

@@ -171,24 +171,21 @@ coding-context -s priority=high implement-feature
 
 ## Task Frontmatter
 
-Task frontmatter is **always** automatically included in the output when present. This happens automatically - no flag is needed. This is useful when downstream tools need access to task metadata.
+Task frontmatter is used for filtering and metadata purposes but is **NOT included in the output**. The frontmatter controls behavior (like auto-filtering rules via the `selectors` field) but only the task content below the frontmatter delimiters is included in the assembled context.
 
 **Example:**
 ```bash
 coding-context implement-feature
 ```
 
-**Output:**
-```yaml
----
-selectors:
-  languages: go
-  stage: implementation
----
+**Output (frontmatter NOT included):**
+```markdown
 # Implement Feature in Go
 ...
 ```
 
+The frontmatter (with `selectors`, `languages`, etc.) is parsed and used to filter rules and control behavior, but it does not appear in the final output sent to the AI agent.
+
 ## Best Practices
 
 1. **Use descriptive task names**: Make them clear and specific

docs/how-to/use-selectors.md

@@ -159,7 +159,7 @@ Use arrays for OR logic within the same selector key:
 ```markdown
 ---
 selectors:
-  language: [go, python, javascript]
+  languages: [go, python, javascript]
   stage: refactoring
 ---
 ```
@@ -203,22 +203,22 @@ coding-context -s environment=production deploy
 
 ### Viewing Task Frontmatter
 
-Task frontmatter (including selectors) is automatically included in the output:
+Task frontmatter (including selectors) is used for filtering and metadata but is **NOT included in the output**. Only the task content appears in the final assembled context.
 
 ```bash
 coding-context implement-feature
 ```
 
-**Output:**
-```yaml
----
-selectors:
-  languages: go
-  stage: implementation
----
-# Task content...
+**Output (frontmatter NOT included):**
+```markdown
+# Implement Feature in Go
+
+Implement the feature following Go best practices and implementation guidelines.
+...
 ```
 
+The frontmatter controls which rules are selected but does not appear in the output sent to the AI agent.
+
 ## Understanding Selector Matching
 
 **Rules are included if:**

docs/reference/cli.md

@@ -316,20 +316,18 @@ This mode is particularly useful when working with AI coding agents that read ru
 ### Standard Output (stdout)
 
 The assembled context, consisting of:
-1. Task frontmatter (YAML format) - always included when task has frontmatter
+1. All matching rule files (content only, without frontmatter)
 2. Available skills metadata (XML format) - included when skills are discovered
-3. All matching rule files
-4. The selected task prompt (with parameters substituted)
+3. The selected task content (with parameters substituted, without frontmatter)
 
-Task frontmatter is automatically included at the beginning of the output when present. This includes all frontmatter fields such as `task_name`, `selectors`, `resume`, `language`, `agent`, and any custom fields.
+**Note:** Task frontmatter is used for filtering and metadata but is **NOT included in the output**. Only the task content below the frontmatter delimiters appears in the final output.
 
-Skills metadata (when present) is output as XML after the task frontmatter and before rules, listing available skills for progressive disclosure.
+Skills metadata (when present) is output as XML after rules and before the task content, listing available skills for progressive disclosure.
 
 **Example output:**
-```yaml
----
-resume: false
----
+```markdown
+# Rule content here...
+
 <available_skills>
   <skill>
     <name>data-analysis</name>
@@ -338,8 +336,6 @@ resume: false
   </skill>
 </available_skills>
 
-# Rule content here...
-
 # Fix Bug Task
 ...
 ```

docs/reference/file-formats.md

@@ -25,18 +25,21 @@ Task files define what the AI agent should do. They are Markdown files with YAML
 Content can include ${parameter_placeholders}.
 ```
 
-**Note:** The `task_name` field is optional. Tasks are matched by filename (without `.md` extension), not by `task_name` in frontmatter. The `task_name` field is useful for metadata and appears in the frontmatter output.
+**Note:** The `task_name` field is optional. Tasks are matched by filename (without `.md` extension), not by `task_name` in frontmatter. The `task_name` field is useful for metadata but task frontmatter is **NOT included in the output** - only the task content below the frontmatter delimiters appears in the final assembled context.
 
 ### Frontmatter Fields
 
 #### `task_name` (optional)
 
 **Type:** String  
-**Purpose:** Metadata field that identifies the task. Tasks are actually matched by filename (without `.md` extension), not by this field. This field is useful for metadata and can be used in task frontmatter output.
+**Purpose:** Metadata field that identifies the task. Tasks are matched by filename (without `.md` extension), not by this field. This field is metadata only.
+
+**Important:** Task frontmatter is **NOT included in the output** - only the task content below the frontmatter delimiters appears in the final assembled context.
 
 **Example:**
 ```yaml
 ---
+task_name: fix-bug
 ---
 ```
 

docs/tutorials/getting-started.md

@@ -24,20 +24,17 @@ This tutorial will guide you through your first steps with the Coding Context CL
 
 ## Step 1: Install the CLI
 
-First, download and install the Coding Context CLI:
+Follow the installation instructions in the main [README](https://github.com/kitproj/coding-context-cli#installation) or use the quick install command for your platform:
 
+**Linux (AMD64):**
 ```bash
-# For Linux
 sudo curl -fsL -o /usr/local/bin/coding-context \
   https://github.com/kitproj/coding-context-cli/releases/download/v0.0.23/coding-context_v0.0.23_linux_amd64
 sudo chmod +x /usr/local/bin/coding-context
-
-# For macOS
-sudo curl -fsL -o /usr/local/bin/coding-context \
-  https://github.com/kitproj/coding-context-cli/releases/download/v0.0.23/coding-context_v0.0.23_darwin_amd64
-sudo chmod +x /usr/local/bin/coding-context
 ```
 
+**macOS (Intel or Apple Silicon):** See [README installation section](https://github.com/kitproj/coding-context-cli#installation)
+
 Verify the installation:
 
 ```bash
@@ -83,8 +80,7 @@ EOF
 ```
 
 **What this does:**
-- The file is named `fix-bug.md`, which is how you'll reference it: `/fix-bug`
-- The frontmatter (`---` section) includes `task_name: fix-bug` as metadata (optional)
+- The file is named `fix-bug.md`, which is how you'll reference it: `fix-bug` (without the `.md` extension)
 - The `${issue_key}` and `${description}` are placeholders that will be replaced with actual values
 - The content provides instructions for the AI agent
 
@@ -128,15 +124,20 @@ coding-context \
   -p issue_key=BUG-123 \
   -p description="Application crashes on startup" \
   -s languages=go \
-  /fix-bug
+  fix-bug
 ```
 
+**Understanding the flags:**
+- **`-p` (parameters)**: Substitutes values into task content placeholders like `${issue_key}`
+- **`-s` (selectors)**: Filters which rules to include based on frontmatter fields like `languages: [ go ]`
+
 **What this command does:**
-- `-p issue_key=BUG-123` replaces `${issue_key}` in the task
-- `-p description="..."` replaces `${description}` in the task
-- `-s languages=go` includes only rules with `languages: [ go ]` in frontmatter
-- `/fix-bug` is the task name to use (slash indicates task file lookup)
-- **Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`)
+- `-p issue_key=BUG-123` replaces `${issue_key}` in the task content
+- `-p description="..."` replaces `${description}` in the task content
+- `-s languages=go` includes only rules with `languages: [ go ]` in their frontmatter
+- `fix-bug` is the task filename to use (matches `fix-bug.md`)
+
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`)
 
 You should see output containing:
 1. The Go coding standards rule
@@ -151,7 +152,7 @@ coding-context \
   -p issue_key=BUG-123 \
   -p description="Application crashes on startup" \
   -s languages=go \
-  /fix-bug | llm -m claude-3-5-sonnet-20241022
+  fix-bug | llm -m claude-3-5-sonnet-20241022
 ```
 
 The AI agent will receive the assembled context and provide a response based on your coding standards and task requirements.
@@ -167,7 +168,7 @@ coding-context \
   -p issue_key=BUG-123 \
   -p description="Application crashes on startup" \
   -s languages=go \
-  /fix-bug | llm -m claude-3-5-sonnet-20241022
+  fix-bug | llm -m claude-3-5-sonnet-20241022
 ```
 
 This is useful for: