Align documentation with code implementation (#167)

* Initial plan

* Fix documentation discrepancies with code implementation

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Fix architecture.md documentation discrepancies

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Fix README agent flag description

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Fix SLIDES.md agent flag description

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

Author: Copilot

README.md

@@ -29,9 +29,9 @@ This tool is compatible with configuration files from various AI coding agents a
 - **[OpenCode.ai](https://opencode.ai/)**: `.opencode/agent`, `.opencode/command`, `.opencode/rules`
 - **[GitHub Copilot](https://github.com/features/copilot)**: `.github/copilot-instructions.md`, `.github/agents`
 - **[Google Gemini](https://gemini.google.com/)**: `GEMINI.md`, `.gemini/styleguide.md`
-- **Generic AI Agents**: `AGENTS.md`, `.agents/rules`, `.agents/commands` (tasks), `.agents/tasks`
+- **Generic AI Agents**: `AGENTS.md`, `.agents/rules`, `.agents/commands` (reusable content blocks), `.agents/tasks`
 
-The tool automatically discovers and includes rules from these locations in your project, parent directories, and user home directory (`~`).
+The tool automatically discovers and includes rules from these locations in your project and user home directory (`~`).
 
 ## Agentic Workflows
 
@@ -106,7 +106,7 @@ Options:
     	Include rules with matching frontmatter. Can be specified multiple times as key=value.
     	Note: Only matches top-level YAML fields in frontmatter.
   -a string
-    	Target agent to use (excludes rules from that agent's own paths). Supported agents: cursor, opencode, copilot, claude, gemini, augment, windsurf, codex.
+    	Target agent to use. Required when using -w to write rules to the agent's user rules path. Supported agents: cursor, opencode, copilot, claude, gemini, augment, windsurf, codex.
   -w	Write rules to agent's config file and output only task to stdout. Requires agent (via task or -a flag).
 ```
 

SLIDES.md

@@ -180,7 +180,7 @@ coding-context -s languages=go -s stage=implementation implement-feature
 | `-C <dir>` | Change to directory before doing anything |
 | `-p key=value` | Parameter to substitute in the prompt |
 | `-s key=value` | Include rules with matching frontmatter |
-| `-a <agent>` | Target agent (excludes that agent's own rules) |
+| `-a <agent>` | Target agent (for -w flag) |
 | `-d <path>` | Remote directory with rules (git::, http://, s3::) |
 | `-m <url>` | URL to manifest file with search paths |
 | `-r` | Resume mode: skip rules, select resume task |

docs/explanation/architecture.md

@@ -54,9 +54,9 @@ The CLI searches for rule files in predetermined locations:
 
 ```
 Search paths (in order):
-1. Project-specific: ./.agents/rules/, ./.cursor/rules/, etc.
-2. Parent directories: ../AGENTS.md, ../../AGENTS.md, etc.
-3. User-specific: ~/.agents/rules/, ~/.claude/CLAUDE.md, etc.
+1. Directories specified via -d flags (in order)
+2. Working directory (automatically added): ./.agents/rules/, ./.cursor/rules/, etc.
+3. User home directory (automatically added): ~/.agents/rules/, ~/.claude/CLAUDE.md, etc.
 ```
 
 For each location:
@@ -155,22 +155,23 @@ Fix bug: BUG-123
 Description: Crashes
 ```
 
-Parameter substitution uses environment variable expansion syntax, allowing:
-- Simple substitution: `${var}`
-- Default values: `${var:-default}`
-- Error on unset: `${var:?error message}`
+If a parameter is not found, the placeholder remains unchanged (e.g., `${missing}` stays as `${missing}`).
 
 ### 9. Assemble Output
 
 Combine all pieces in order:
 
 ```
-1. All included rule files (content only, no frontmatter)
-2. Task content (with parameters substituted)
+1. Task frontmatter (YAML format, automatically included if present)
+2. All included rule files (content only, no frontmatter)
+3. Task content (with parameters substituted)
 ```
 
 **Example output:**
-```markdown
+```yaml
+---
+resume: false
+---
 # Go Coding Standards
 
 - Use gofmt

docs/reference/file-formats.md

@@ -798,12 +798,12 @@ coding-context -s languages=go task      # Matches languages: [ go ]
 
 ## Special Behaviors
 
-### Multiple Tasks with Same `task_name`
+### Multiple Tasks with Same Filename
 
-If multiple task files have the same `task_name`, selectors determine which one is used.
+If multiple task files have the same filename (without `.md` extension) in different search path directories, selectors determine which one is used. Remember, tasks are matched by filename, not by the `task_name` field in frontmatter.
 
 **Without selectors:**
-- Error: "multiple tasks found with task_name: X"
+- Error: "multiple tasks found with name: X"
 
 **With selectors:**
 - The task matching all selectors is used