docs: verify and fix documentation against code implementation

README.md

@@ -154,7 +154,7 @@ The tool assembles the context in the following order:
 1.  **Rule Files**: It searches a list of predefined locations for rule files (`.md` or `.mdc`). These locations include the current directory, ancestor directories, user's home directory, and system-wide directories.
 2.  **Rule Bootstrap Scripts**: For each rule file found (e.g., `my-rule.md`), it looks for an executable script named `my-rule-bootstrap`. If found, it runs the script before processing the rule file. These scripts are meant for bootstrapping the environment (e.g., installing tools) and their output is sent to `stderr`, not into the main context.
 3.  **Filtering**: If `-s` (include) flag is used, it parses the YAML frontmatter of each rule file to decide whether to include it. Note that selectors can only match top-level YAML fields (e.g., `language: go`), not nested fields.
-4.  **Task Prompt**: It searches for a task file with `task_name: <task-name>` in its frontmatter. The filename doesn't matter. If selectors are provided with `-s`, they are used to filter between multiple task files with the same `task_name`.
+4.  **Task Prompt**: It searches for a task file matching the filename (without `.md` extension). Tasks are matched by filename, not by `task_name` in frontmatter. If selectors are provided with `-s`, they are used to filter between multiple task files with the same filename.
 5.  **Task Bootstrap Script**: For the task file found (e.g., `fix-bug.md`), it looks for an executable script named `fix-bug-bootstrap`. If found, it runs the script before processing the task file. This allows task-specific environment setup or data preparation.
 6.  **Parameter Expansion**: It substitutes variables in the task prompt using the `-p` flags.
 7.  **Output**: It prints the content of all included rule files, followed by the expanded task prompt, to standard output.
@@ -542,7 +542,7 @@ echo "Fetching issue information..." >&2
 
 ### Task Frontmatter
 
-Task frontmatter is automatically included at the beginning of the output. This allows the AI agent or downstream tool to access metadata about the task being executed.
+Task frontmatter is **always** automatically included at the beginning of the output when a task file has frontmatter. This allows the AI agent or downstream tool to access metadata about the task being executed. There is no flag needed to enable this - it happens automatically.
 
 **Example usage:**
 ```bash

docs/explanation/agentic-workflows.md

@@ -91,7 +91,7 @@ Context is assembled at runtime based on the specific task:
 
 ```bash
 # Bug fix: Include only relevant rules
-coding-context -s language=Go -s priority=high /fix-bug
+coding-context -s languages=go -s priority=high /fix-bug
 
 # Code review: Different context
 coding-context -s stage=review /code-review

docs/explanation/architecture.md

@@ -24,12 +24,12 @@ Each stage transforms data before passing it to the next stage.
 ### 1. Parse Command-Line Arguments
 
 ```
-coding-context -C /project -s language=Go -p issue=BUG-123 /fix-bug
+coding-context -C /project -s languages=go -p issue=BUG-123 /fix-bug
 ```
 
 The CLI parses:
 - Working directory: `/project`
-- Selectors: `{language: Go}`
+- Selectors: `{languages: go}`
 - Parameters: `{issue: BUG-123}`
 - Task name: `fix-bug`
 
@@ -81,7 +81,7 @@ If found: Execute and log output to stderr
 
 ### 5. Filter Rules by Selectors
 
-If selectors are specified (e.g., `-s language=Go`):
+If selectors are specified (e.g., `-s languages=go`):
 
 ```
 For each rule:
@@ -96,14 +96,15 @@ For each rule:
 ```yaml
 # Rule 1
 ---
-language: Go
+languages:
+  - go
 stage: testing
 ---
 ```
-- `-s language=Go` → ✅ Include
-- `-s language=Python` → ❌ Exclude
-- `-s language=Go -s stage=testing` → ✅ Include
-- `-s language=Go -s stage=planning` → ❌ Exclude
+- `-s languages=go` → ✅ Include
+- `-s languages=python` → ❌ Exclude
+- `-s languages=go -s stage=testing` → ✅ Include
+- `-s languages=go -s stage=planning` → ❌ Exclude
 
 Rules without frontmatter are always included (unless resume mode).
 
@@ -333,7 +334,7 @@ Searched:
   - ./.agents/tasks/
   - ~/.agents/tasks/
 
-Tip: Check that your task file has 'task_name: fix-bug' in frontmatter
+Tip: Check that your task file is named `fix-bug.md` (tasks are matched by filename, not by `task_name` in frontmatter)
 ```
 
 ## Design Principles
@@ -371,13 +372,15 @@ Selectors only match top-level YAML fields:
 ```yaml
 # ✅ Can match
 ---
-language: Go
+languages:
+  - go
 ---
 
 # ❌ Cannot match nested
 ---
 metadata:
-  language: Go
+  languages:
+    - go
 ---
 ```
 
@@ -386,10 +389,10 @@ metadata:
 Multiple selectors use AND logic:
 
 ```bash
-# Requires BOTH language=Go AND stage=testing
-coding-context -s language=Go -s stage=testing /fix-bug
+# Requires BOTH languages=go AND stage=testing
+coding-context -s languages=go -s stage=testing /fix-bug
 
-# No way to specify: language=Go OR language=Python
+# No way to specify: languages=go OR languages=python
 ```
 
 ### No Rule Ordering

docs/how-to/create-rules.md

@@ -33,7 +33,8 @@ Create rules that apply only to specific programming languages:
 **Go standards (`.agents/rules/go-standards.md`):**
 ```markdown
 ---
-language: Go
+languages:
+  - go
 ---
 
 # Go Coding Standards
@@ -47,7 +48,8 @@ language: Go
 **Python standards (`.agents/rules/python-standards.md`):**
 ```markdown
 ---
-language: Python
+languages:
+  - python
 ---
 
 # Python Coding Standards
@@ -61,19 +63,22 @@ language: Python
 Use with:
 ```bash
 # Include only Go rules
-coding-context -s language=Go /fix-bug
+coding-context -s languages=go /fix-bug
 
 # Include only Python rules
-coding-context -s language=Python /fix-bug
+coding-context -s languages=python /fix-bug
 ```
 
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`).
+
 ## Rules with Multiple Selectors
 
 Create rules with multiple frontmatter fields for fine-grained filtering:
 
 ```markdown
 ---
-language: Go
+languages:
+  - go
 stage: testing
 priority: high
 ---
@@ -90,9 +95,11 @@ When writing tests:
 Use with:
 ```bash
 # Include rules for Go testing
-coding-context -s language=Go -s stage=testing /implement-feature
+coding-context -s languages=go -s stage=testing /implement-feature
 ```
 
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`).
+
 ## Stage-Specific Rules
 
 Create rules for different workflow stages:
@@ -179,24 +186,26 @@ coding-context -s source=jira /fix-bug
 
 1. **Keep rules focused**: Each rule should address one concern
 2. **Use frontmatter selectors**: Make rules conditionally includable
-3. **Match language names exactly**: Use GitHub Linguist names (e.g., `Go`, not `go`)
+3. **Use lowercase language values**: Language values should be lowercase (e.g., `go`, `python`, `javascript`)
 4. **Organize by category**: Group related rules together
 5. **Update rules as standards evolve**: Keep them current
 
-## Common Linguist Languages
+## Common Language Values
+
+Use lowercase values in your `language:` frontmatter:
 
-Use these exact names in your `language:` frontmatter:
+- c, c++, c#, css
+- dart, elixir, go
+- haskell, html
+- java, javascript
+- kotlin, lua
+- markdown, objective-c
+- php, python
+- ruby, rust
+- scala, shell, swift
+- typescript, yaml
 
-- C, C++, C#, CSS
-- Dart, Elixir, Go
-- Haskell, HTML
-- Java, JavaScript
-- Kotlin, Lua
-- Markdown, Objective-C
-- PHP, Python
-- Ruby, Rust
-- Scala, Shell, Swift
-- TypeScript, YAML
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`).
 
 ## See Also
 

docs/how-to/create-tasks.md

@@ -139,7 +139,7 @@ Instead of requiring `-s` flags on every invocation, you can embed selectors dir
 ---
 task_name: implement-feature
 selectors:
-  language: Go
+  languages: go
   stage: implementation
 ---
 # Implement Feature in Go
@@ -152,7 +152,7 @@ Requirements: ${requirements}
 
 **Usage:**
 ```bash
-# Automatically applies language=Go and stage=implementation selectors
+# Automatically applies languages=go and stage=implementation selectors
 coding-context -p feature_name="User Auth" /implement-feature
 ```
 
@@ -161,27 +161,29 @@ coding-context -p feature_name="User Auth" /implement-feature
 ---
 task_name: write-tests
 selectors:
-  language: [Go, Python]
+  languages: [go, python]
   stage: testing
 ---
 # Write Tests
 
 Write comprehensive tests for the code.
 ```
 
-This matches rules where `(language=Go OR language=Python) AND stage=testing`.
+This matches rules where `(languages=go OR languages=python) AND stage=testing`.
 
 **Combining embedded and command-line selectors:**
 ```bash
-# Task has: selectors.language = Go
+# Task has: selectors.languages = go
 # Command adds: -s priority=high
-# Result: Includes rules matching language=Go AND priority=high
+# Result: Includes rules matching languages=go AND priority=high
 coding-context -s priority=high /implement-feature
 ```
 
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`).
+
 ## Task Frontmatter
 
-Task frontmatter is automatically included in the output. This is useful when downstream tools need access to task metadata.
+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.
 
 **Example:**
 ```bash
@@ -193,7 +195,7 @@ coding-context /implement-feature
 ---
 task_name: implement-feature
 selectors:
-  language: Go
+  languages: go
   stage: implementation
 ---
 # Implement Feature in Go

docs/how-to/github-actions.md

@@ -209,7 +209,7 @@ Use the `-C` flag to run from a different directory:
 ```yaml
 - name: Assemble Context
   run: |
-    coding-context -C ./backend -s language=Go /fix-bug > context.txt
+    coding-context -C ./backend -s languages=go /fix-bug > context.txt
 ```
 
 ## Best Practices

docs/how-to/use-remote-directories.md

@@ -126,7 +126,7 @@ Combine remote directories with local project rules:
 # 3. Home directory (automatically added)
 coding-context \
   -d git::https://github.com/company/shared-rules.git \
-  -s language=Go \
+  -s languages=go \
   /fix-bug
 ```
 
@@ -137,7 +137,7 @@ You can also explicitly add local directories:
 coding-context \
   -d git::https://github.com/company/shared-rules.git \
   -d file:///path/to/local/rules \
-  -s language=Go \
+  -s languages=go \
   /fix-bug
 ```
 
@@ -150,7 +150,7 @@ Use remote directories with all normal CLI features:
 ```bash
 coding-context \
   -d git::https://github.com/company/standards.git \
-  -s language=Go \
+  -s languages=go \
   -s environment=production \
   -p component=auth \
   -p severity=critical \
@@ -203,7 +203,8 @@ mkdir -p .agents/tasks
 **`.agents/rules/go-standards.md`:**
 ```markdown
 ---
-language: Go
+languages:
+  - go
 ---
 
 # Go Coding Standards
@@ -259,7 +260,7 @@ git push --tags
 # In any project
 coding-context \
   -d 'git::https://github.com/company/shared-coding-rules.git?ref=v1.0.0' \
-  -s language=Go \
+  -s languages=go \
   /code-review
 ```