Fix documentation inconsistencies with code implementation (#144)

* Initial plan

* Fix README.md: task search paths, language field naming, add -m flag

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

* Fix reference docs: task_names plural, task vs command paths, add -m flag

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

* Fix architecture and how-to docs for task matching consistency

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

* Remove slash prefix from task invocation examples throughout docs

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

@@ -86,6 +86,8 @@ Options:
     	Change to directory before doing anything. (default ".")
   -d value
     	Remote directory containing rules and tasks. Can be specified multiple times. Supports various protocols via go-getter (http://, https://, git::, s3::, etc.).
+  -m string
+    	Go Getter URL to a manifest file containing search paths (one per line). Every line is included as-is.
   -p value
     	Parameter to substitute in the prompt. Can be specified multiple times as key=value.
   -r	Resume mode: skip outputting rules and select task with 'resume: true' in frontmatter.
@@ -166,18 +168,20 @@ The tool looks for task and rule files in the following locations, in order of p
 
 **Tasks:**
 - `./.agents/tasks/*.md` (task name matches filename without `.md` extension)
+- `~/.agents/tasks/*.md`
+
+**Commands** (referenced via slash commands inside task content):
 - `./.agents/commands/*.md`
 - `./.cursor/commands/*.md`
 - `./.opencode/command/*.md`
-- `~/.agents/tasks/*.md`
 
 **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`, `.opencode/command`
-- `.github/copilot-instructions.md`, `.gemini/styleguide.md`
-- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` (and in parent directories)
-- User-specific rules in `~/.agents/rules`, `~/.claude/CLAUDE.md`, `~/.opencode/rules`, etc.
+- `.agents/rules`, `.cursor/rules`, `.augment/rules`, `.windsurf/rules`, `.opencode/agent`, `.opencode/rules`
+- `.github/copilot-instructions.md`, `.github/agents`, `.gemini/styleguide.md`
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.codex/AGENTS.md`
+- User-specific rules in `~/.agents/rules`, `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.opencode/rules`, etc.
 
 ### Remote File System Support
 
@@ -203,7 +207,7 @@ coding-context \
 # Mix local and remote directories
 coding-context \
   -d git::https://github.com/company/shared-rules.git \
-  -s language=Go \
+  -s languages=go \
   /implement-feature
 ```
 
@@ -290,7 +294,7 @@ Task files can include a `selectors` field in their frontmatter to automatically
 ---
 task_name: implement-feature
 selectors:
-  language: Go
+  languages: go
   stage: implementation
 ---
 # Implement Feature
@@ -300,34 +304,34 @@ Implement the feature following Go best practices and implementation guidelines.
 
 When you run this task, it automatically applies the selectors:
 ```bash
-# This command automatically includes only rules with language=Go and stage=implementation
-coding-context /implement-feature
+# This command automatically includes only rules with languages=go and stage=implementation
+coding-context implement-feature
 ```
 
 This is equivalent to:
 ```bash
-coding-context -s language=Go -s stage=implementation /implement-feature
+coding-context -s languages=go -s stage=implementation /implement-feature
 ```
 
 **Selectors support OR logic for the same key using arrays:**
 ```markdown
 ---
 task_name: test-code
 selectors:
-  language: [Go, Python]
+  languages: [go, python]
   stage: testing
 ---
 ```
 
-This will include rules that match `(language=Go OR language=Python) AND stage=testing`.
+This will include rules that match `(languages=go OR languages=python) AND stage=testing`.
 
 **Combining task selectors with command-line selectors:**
 
 Selectors from both the task frontmatter and command line are combined (additive):
 ```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
 ```
 
@@ -389,7 +393,8 @@ Rule files are Markdown (`.md`) or `.mdc` files, optionally with YAML frontmatte
 **Example (`.agents/rules/backend.md`):**
 ```markdown
 ---
-language: Go
+languages:
+  - go
 ---
 
 # Backend Coding Standards
@@ -398,65 +403,57 @@ language: Go
 - Use the standard logging library.
 ```
 
-To include this rule only when working on Go code, you would use `-s language=Go`:
+To include this rule only when working on Go code, you would use `-s languages=go`:
 
 ```bash
-coding-context -s language=Go /fix-bug
+coding-context -s languages=go /fix-bug
 ```
 
-This will include all rules with `language: Go` in their frontmatter, excluding rules for other languages.
+This will include all rules with `languages: [ go ]` in their frontmatter, excluding rules for other languages.
+
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`). The frontmatter field is `languages` (plural) with array format.
 
 **Example: Language-Specific Rules**
 
 You can create multiple language-specific rule files:
 
-- `.agents/rules/python-standards.md` with `language: Python`
-- `.agents/rules/javascript-standards.md` with `language: JavaScript`
-- `.agents/rules/go-standards.md` with `language: Go`
+- `.agents/rules/python-standards.md` with `languages: [ python ]`
+- `.agents/rules/javascript-standards.md` with `languages: [ javascript ]`
+- `.agents/rules/go-standards.md` with `languages: [ go ]`
 
 Then select only the relevant rules:
 
 ```bash
 # Work on Python code with Python-specific rules
-coding-context -s language=Python /fix-bug
+coding-context -s languages=python /fix-bug
 
 # Work on JavaScript code with JavaScript-specific rules
-coding-context -s language=JavaScript /enhance-feature
-```
-
-**Common Linguist Languages**
-
-When using language selectors, use the exact language names as defined by [GitHub Linguist](https://github.com/github-linguist/linguist/blob/master/lib/linguist/languages.yml). Here are common languages with correct capitalization:
-
-- **C**: `C`
-- **C#**: `C#`
-- **C++**: `C++`
-- **CSS**: `CSS`
-- **Dart**: `Dart`
-- **Elixir**: `Elixir`
-- **Go**: `Go`
-- **Haskell**: `Haskell`
-- **HTML**: `HTML`
-- **Java**: `Java`
-- **JavaScript**: `JavaScript`
-- **Kotlin**: `Kotlin`
-- **Lua**: `Lua`
-- **Markdown**: `Markdown`
-- **Objective-C**: `Objective-C`
-- **PHP**: `PHP`
-- **Python**: `Python`
-- **Ruby**: `Ruby`
-- **Rust**: `Rust`
-- **Scala**: `Scala`
-- **Shell**: `Shell`
-- **Swift**: `Swift`
-- **TypeScript**: `TypeScript`
-- **YAML**: `YAML`
-
-Note the capitalization - for example, use `Go` not `go`, `JavaScript` not `javascript`, and `TypeScript` not `typescript`.
+coding-context -s languages=javascript /enhance-feature
+```
+
+**Language Values**
+
+When using language selectors, language values should be **lowercase** (e.g., `go`, `python`, `javascript`, `java`, `typescript`). The frontmatter field should be `languages` (plural) in array format:
+
+```yaml
+---
+languages:
+  - go
+  - python
+---
+```
+
+**Common languages (lowercase):**
+- `c`, `csharp` (C#), `cpp` (C++), `css`
+- `dart`, `elixir`, `go`, `haskell`, `html`
+- `java`, `javascript`, `kotlin`, `lua`, `markdown`
+- `objectivec` (Objective-C), `php`, `python`, `ruby`, `rust`
+- `scala`, `shell`, `swift`, `typescript`, `yaml`
+
+**Note:** Language values should be lowercase in frontmatter and selectors.
 
 **Note:** Frontmatter selectors can only match top-level YAML fields. For example:
-- ✅ Works: `language: Go` matches `-s language=Go`
+- ✅ Works: `languages: [ go ]` matches `-s languages=go`
 - ❌ Doesn't work: Nested fields like `metadata.version: 1.0` cannot be matched with `-s metadata.version=1.0`
 
 If you need to filter on nested data, flatten your frontmatter structure to use top-level fields only.
@@ -567,15 +564,15 @@ This can be useful for:
 
 **Example with selectors in frontmatter:**
 ```bash
-coding-context /implement-feature
+coding-context implement-feature
 ```
 
 If the task has `selectors` in its frontmatter, they will be visible in the output:
 ```yaml
 ---
 task_name: implement-feature
 selectors:
-  language: Go
+  languages: go
   stage: implementation
 ---
 # Implementation Task

docs/explanation/agentic-workflows.md

@@ -116,7 +116,7 @@ Scripts fetch current state before agent execution:
 ```bash
 # Fetch JIRA issue details automatically
 export JIRA_ISSUE_KEY="BUG-123"
-coding-context /fix-bug  # Bootstrap fetches latest data
+coding-context fix-bug  # Bootstrap fetches latest data
 ```
 
 ## The Agentic Workflow Ecosystem

docs/explanation/architecture.md

@@ -110,7 +110,7 @@ Rules without frontmatter are always included (unless resume mode).
 
 ### 6. Discover Task Files
 
-Search task file locations for files with matching `task_name`:
+Search task file locations for files with matching filename:
 
 ```
 Search paths:
@@ -119,11 +119,13 @@ Search paths:
 ```
 
 For each `.md` file:
+- Check if filename (without `.md` extension) matches requested task name
 - Parse frontmatter
-- Check if `task_name` matches requested task
 - Check if selectors match (if specified)
 - Store matching tasks
 
+**Note:** Tasks are matched by filename, not by `task_name` in frontmatter. The `task_name` field is optional metadata.
+
 ### 7. Select Task
 
 From matching tasks:

docs/how-to/create-tasks.md

@@ -29,7 +29,7 @@ Save as `.agents/tasks/code-review.md` (or `.agents/commands/code-review.md`).
 
 Use with:
 ```bash
-coding-context /code-review
+coding-context code-review
 ```
 
 ## Task with Parameters
@@ -187,7 +187,7 @@ Task frontmatter is **always** automatically included in the output when present
 
 **Example:**
 ```bash
-coding-context /implement-feature
+coding-context implement-feature
 ```
 
 **Output:**

docs/how-to/use-selectors.md

@@ -100,7 +100,7 @@ coding-context -s stage=testing /test-feature
 coding-context -s priority=high /fix-critical-bug
 
 # Include all priorities (no selector)
-coding-context /fix-bug
+coding-context fix-bug
 ```
 
 ### By Source
@@ -146,7 +146,7 @@ selectors:
 **Usage:**
 ```bash
 # Automatically applies language=go and stage=implementation
-coding-context /implement-feature
+coding-context implement-feature
 ```
 
 This is equivalent to:
@@ -171,7 +171,7 @@ selectors:
 **Usage:**
 ```bash
 # Includes rules matching (go OR python OR javascript) AND refactoring
-coding-context /refactor-code
+coding-context refactor-code
 ```
 
 ### Combining Command-Line and Task Selectors
@@ -211,7 +211,7 @@ coding-context -s environment=production /deploy
 Task frontmatter (including selectors) is automatically included in the output:
 
 ```bash
-coding-context /implement-feature
+coding-context implement-feature
 ```
 
 **Output:**
@@ -303,7 +303,8 @@ coding-context -s languages=go /fix-bug 2>&1 | grep -i token
 - Verify unique frontmatter values across rules
 
 **Task not found:**
-- Ensure `task_name` matches exactly
+- Ensure filename (without `.md` extension) matches the task name exactly
+- Tasks are matched by filename, not by `task_name` in frontmatter
 - Check that selectors don't over-filter (try without selectors)
 
 ## See Also

docs/how-to/use-with-ai-agents.md

@@ -14,7 +14,7 @@ This guide shows you how to use the Coding Context CLI with various AI agents an
 Pipe the assembled context to any AI agent:
 
 ```bash
-coding-context /fix-bug | your-ai-agent
+coding-context fix-bug | your-ai-agent
 ```
 
 ## With Claude CLI
@@ -29,7 +29,7 @@ coding-context \
 ## With OpenAI API
 
 ```bash
-coding-context /code-review | openai api completions.create \
+coding-context code-review | openai api completions.create \
   -m gpt-4 \
   --stream
 ```
@@ -40,13 +40,13 @@ The [llm](https://llm.datasette.io/) tool supports many models:
 
 ```bash
 # Using Claude
-coding-context /fix-bug | llm -m claude-3-5-sonnet-20241022
+coding-context fix-bug | llm -m claude-3-5-sonnet-20241022
 
 # Using Gemini
-coding-context /code-review | llm -m gemini-pro
+coding-context code-review | llm -m gemini-pro
 
 # Using local models
-coding-context /implement-feature | llm -m llama2
+coding-context implement-feature | llm -m llama2
 ```
 
 ## Saving Context to File
@@ -55,7 +55,7 @@ Save the context for later use or inspection:
 
 ```bash
 # Save to file
-coding-context /fix-bug > context.txt
+coding-context fix-bug > context.txt
 
 # Review the context
 cat context.txt
@@ -84,7 +84,7 @@ If you're using GitHub Copilot, the CLI can prepare context for custom instructi
 
 ```bash
 # Generate context
-coding-context /implement-feature > .github/copilot-context.md
+coding-context implement-feature > .github/copilot-context.md
 
 # Copilot will read this file automatically
 ```
@@ -109,10 +109,10 @@ The CLI prints token estimates to stderr:
 
 ```bash
 # See token count while piping to AI
-coding-context /fix-bug 2>&1 | tee >(grep -i token >&2) | ai-agent
+coding-context fix-bug 2>&1 | tee >(grep -i token >&2) | ai-agent
 
 # Or redirect stderr to file
-coding-context /fix-bug 2> tokens.log | ai-agent
+coding-context fix-bug 2> tokens.log | ai-agent
 ```
 
 ## Batch Processing