diff --git a/README.md b/README.md
index f581804f..44fa86eb 100644
--- a/README.md
+++ b/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
diff --git a/docs/explanation/agentic-workflows.md b/docs/explanation/agentic-workflows.md
index 76790e73..3e460bf8 100644
--- a/docs/explanation/agentic-workflows.md
+++ b/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
diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md
index dac80697..c7fa4351 100644
--- a/docs/explanation/architecture.md
+++ b/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
diff --git a/docs/how-to/create-rules.md b/docs/how-to/create-rules.md
index 428ed11f..8d209113 100644
--- a/docs/how-to/create-rules.md
+++ b/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
 
diff --git a/docs/how-to/create-tasks.md b/docs/how-to/create-tasks.md
index 03736e56..f94cb2e5 100644
--- a/docs/how-to/create-tasks.md
+++ b/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,7 +161,7 @@ coding-context -p feature_name="User Auth" /implement-feature
 ---
 task_name: write-tests
 selectors:
-  language: [Go, Python]
+  languages: [go, python]
   stage: testing
 ---
 # Write Tests
@@ -169,19 +169,21 @@ selectors:
 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
diff --git a/docs/how-to/github-actions.md b/docs/how-to/github-actions.md
index 85e24cd0..30ddcaff 100644
--- a/docs/how-to/github-actions.md
+++ b/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
diff --git a/docs/how-to/use-remote-directories.md b/docs/how-to/use-remote-directories.md
index b9debfe6..5f7bbac3 100644
--- a/docs/how-to/use-remote-directories.md
+++ b/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
 ```
 
diff --git a/docs/how-to/use-selectors.md b/docs/how-to/use-selectors.md
index d7f05c5a..317bc6ea 100644
--- a/docs/how-to/use-selectors.md
+++ b/docs/how-to/use-selectors.md
@@ -15,10 +15,10 @@ Include only rules matching a specific frontmatter field:
 
 ```bash
 # Include only Go rules
-coding-context -s language=Go /fix-bug
+coding-context -s languages=go /fix-bug
 ```
 
-This includes only rules with `language: Go` in their frontmatter.
+This includes only rules with `languages: [ go ]` in their frontmatter.
 
 ## Multiple Selectors (AND Logic)
 
@@ -26,10 +26,12 @@ Combine multiple selectors - all must match:
 
 ```bash
 # Include only Go testing rules
-coding-context -s language=Go -s stage=testing /implement-feature
+coding-context -s languages=go -s stage=testing /implement-feature
 ```
 
-This includes only rules with BOTH `language: Go` AND `stage: testing`.
+This includes only rules with BOTH `languages: [ go ]` AND `stage: testing`.
+
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`).
 
 ## Selecting Tasks
 
@@ -68,14 +70,14 @@ coding-context -s environment=production /deploy
 
 ```bash
 # Python project
-coding-context -s language=Python /fix-bug
+coding-context -s languages=python /fix-bug
 
 # JavaScript project
-coding-context -s language=JavaScript /code-review
+coding-context -s languages=javascript /code-review
 
 # Multi-language (run separately)
-coding-context -s language=Go /implement-backend
-coding-context -s language=JavaScript /implement-frontend
+coding-context -s languages=go /implement-backend
+coding-context -s languages=javascript /implement-frontend
 ```
 
 ### By Stage
@@ -134,7 +136,7 @@ Instead of specifying selectors on the command line every time, you can embed th
 ---
 task_name: implement-feature
 selectors:
-  language: go
+  languages: go
   stage: implementation
 ---
 # Implement Feature in Go
@@ -149,7 +151,7 @@ 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
 ```
 
 ### Array Selectors (OR Logic)
@@ -217,7 +219,7 @@ coding-context /implement-feature
 ---
 task_name: implement-feature
 selectors:
-  language: go
+  languages: go
   stage: implementation
 ---
 # Task content...
@@ -230,9 +232,11 @@ selectors:
 - All specified selectors match the rule's frontmatter
 
 **Tasks are selected by:**
-- Matching `task_name` (required)
+- Matching filename (without `.md` extension)
 - Matching all selectors (if specified)
 
+**Note:** Tasks are matched by filename, not by `task_name` in frontmatter. The `task_name` field is optional metadata.
+
 **Important limitations:**
 - Only top-level frontmatter fields can be matched
 - Nested fields (e.g., `metadata.version`) are NOT supported
@@ -243,7 +247,8 @@ selectors:
 **Rule with multiple frontmatter fields:**
 ```markdown
 ---
-language: Go
+languages:
+  - go
 stage: testing
 priority: high
 team: backend
@@ -256,13 +261,13 @@ team: backend
 **Matching selectors:**
 ```bash
 # Matches
-coding-context -s language=Go /fix-bug
-coding-context -s language=Go -s stage=testing /fix-bug
+coding-context -s languages=go /fix-bug
+coding-context -s languages=go -s stage=testing /fix-bug
 coding-context -s priority=high /fix-bug
 
 # Does NOT match
-coding-context -s language=Python /fix-bug
-coding-context -s language=Go -s stage=planning /fix-bug
+coding-context -s languages=python /fix-bug
+coding-context -s languages=go -s stage=planning /fix-bug
 ```
 
 ## Debugging Selectors
@@ -271,11 +276,11 @@ Check which rules are included:
 
 ```bash
 # Output to file and review
-coding-context -s language=Go /fix-bug > output.txt
+coding-context -s languages=go /fix-bug > output.txt
 less output.txt
 
 # Check token count
-coding-context -s language=Go /fix-bug 2>&1 | grep -i token
+coding-context -s languages=go /fix-bug 2>&1 | grep -i token
 ```
 
 ## Best Practices
diff --git a/docs/how-to/use-with-ai-agents.md b/docs/how-to/use-with-ai-agents.md
index 41f497fb..bbf55b8b 100644
--- a/docs/how-to/use-with-ai-agents.md
+++ b/docs/how-to/use-with-ai-agents.md
@@ -22,7 +22,7 @@ coding-context /fix-bug | your-ai-agent
 ```bash
 coding-context \
   -p issue_key=BUG-123 \
-  -s language=Go \
+  -s languages=go \
   /fix-bug | claude
 ```
 
@@ -140,7 +140,7 @@ ISSUE_KEY=$1
 DESCRIPTION=$2
 
 coding-context \
-  -s language=Go \
+  -s languages=go \
   -s priority=high \
   -p issue_key="$ISSUE_KEY" \
   -p description="$DESCRIPTION" \
@@ -159,7 +159,7 @@ If your context exceeds token limits:
 
 1. **Use selectors to reduce included rules:**
    ```bash
-   coding-context -s language=Go -s priority=high /fix-bug
+   coding-context -s languages=go -s priority=high /fix-bug
    ```
 
 2. **Use resume mode to skip rules:**
diff --git a/docs/index.md b/docs/index.md
index 622beb9f..07f58f51 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -19,7 +19,7 @@ sudo curl -fsL -o /usr/local/bin/coding-context \
 sudo chmod +x /usr/local/bin/coding-context
 
 # Use with an AI agent
-coding-context -p issue_key=BUG-123 -s language=Go /fix-bug | llm -m claude-3-5-sonnet-20241022
+coding-context -p issue_key=BUG-123 -s languages=go /fix-bug | llm -m claude-3-5-sonnet-20241022
 ```
 
 ## Documentation Structure
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 186bb42c..a53d3b63 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -93,7 +93,7 @@ coding-context \
 coding-context \
   -d git::https://github.com/company/org-standards.git \
   -d file:///path/to/local/rules \
-  -s language=Go \
+  -s languages=go \
   /fix-bug
 
 # Local directories are automatically included
@@ -150,75 +150,53 @@ coding-context -r /fix-bug | ai-agent
 
 Filter rules and tasks by frontmatter fields. Only rules and tasks where ALL specified selectors match will be included.
 
-**Important:** Only top-level frontmatter fields can be matched. Nested fields are not supported.
+**Important:** 
+- Only top-level frontmatter fields can be matched. Nested fields are not supported.
+- For language filtering, use `-s languages=go` (plural `languages`)
+- This is different from the `-p` flag, which is for parameter substitution, not filtering
 
 **Examples:**
 ```bash
 # Single selector
-coding-context -s language=Go /fix-bug
+coding-context -s languages=go /fix-bug
 
 # Multiple selectors (AND logic)
-coding-context -s language=Go -s priority=high /fix-bug
+coding-context -s languages=go -s priority=high /fix-bug
 
 # Select specific task variant
 coding-context -s environment=production /deploy
 ```
 
-### `-t`
+**Note:** When filtering by language, use `-s languages=go` (plural). The selector key is `languages` (plural), matching the frontmatter field name.
 
-**Type:** Boolean flag  
-**Default:** False
+## Exit Codes
 
-Print the task's YAML frontmatter at the beginning of the output. This includes all frontmatter fields such as `task_name`, `selectors`, `resume`, and any custom fields.
+- `0` - Success
+- Non-zero - Error occurred (check stderr for details)
 
-Use this when downstream tools or AI agents need access to task metadata for decision-making or workflow automation.
+## Output
 
-**Example:**
-```bash
-# Emit task frontmatter with the assembled context
-coding-context -t /fix-bug
-```
+### Standard Output (stdout)
+
+The assembled context, consisting of:
+1. Task frontmatter (YAML format) - always included when task has frontmatter
+2. All matching rule files
+3. The selected task prompt (with parameters substituted)
 
-**Output:**
+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.
+
+**Example output:**
 ```yaml
 ---
 task_name: fix-bug
 resume: false
 ---
-# Fix Bug Task
-...
-```
-
-**Example with selectors:**
-```bash
-coding-context -t /implement-feature
-```
+# Rule content here...
 
-If the task includes `selectors` in frontmatter, they appear in the output:
-```yaml
----
-task_name: implement-feature
-selectors:
-  language: Go
-  stage: implementation
----
-# Implementation
+# Fix Bug Task
 ...
 ```
 
-## Exit Codes
-
-- `0` - Success
-- Non-zero - Error occurred (check stderr for details)
-
-## Output
-
-### Standard Output (stdout)
-
-The assembled context, consisting of:
-1. All matching rule files
-2. The selected task prompt (with parameters substituted)
-
 This output is intended to be piped to an AI agent.
 
 ### Standard Error (stderr)
@@ -263,11 +241,11 @@ coding-context "/fix-bug 123"
 coding-context -p pr_number=123 /code-review
 
 # With selectors
-coding-context -s language=Python /fix-bug
+coding-context -s languages=python /fix-bug
 
 # Multiple parameters and selectors
 coding-context \
-  -s language=Go \
+  -s languages=go \
   -s stage=implementation \
   -p feature_name="Authentication" \
   /implement-feature
@@ -297,7 +275,7 @@ coding-context -d 'git::https://github.com/company/rules.git?ref=v1.0.0' /fix-bu
 coding-context \
   -d git::https://github.com/company/org-standards.git \
   -d git::https://github.com/team/project-rules.git \
-  -s language=Go \
+  -s languages=go \
   /implement-feature
 
 # Load from HTTP archive
@@ -357,25 +335,28 @@ Selectors (`-s`) only match top-level YAML frontmatter fields.
 **Works:**
 ```yaml
 ---
-language: Go
+languages:
+  - go
 stage: testing
 ---
 ```
 ```bash
-coding-context -s language=Go -s stage=testing /fix-bug
+coding-context -s languages=go -s stage=testing /fix-bug
 ```
 
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`). Use `languages:` (plural) with array format in frontmatter.
+
 **Doesn't Work:**
 ```yaml
 ---
 metadata:
-  language: Go
+  languages: go
   stage: testing
 ---
 ```
 ```bash
 # This WON'T match nested fields
-coding-context -s metadata.language=Go /fix-bug
+coding-context -s metadata.language=go /fix-bug
 ```
 
 ## Slash Commands
diff --git a/docs/reference/file-formats.md b/docs/reference/file-formats.md
index 5b5c74f1..38973db9 100644
--- a/docs/reference/file-formats.md
+++ b/docs/reference/file-formats.md
@@ -17,7 +17,7 @@ Task files define what the AI agent should do. They are Markdown files with YAML
 
 ```markdown
 ---
-task_name: <required-task-identifier>
+task_name: <optional-task-identifier>
 <optional-frontmatter-fields>
 ---
 
@@ -26,12 +26,14 @@ task_name: <required-task-identifier>
 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.
+
 ### Frontmatter Fields
 
-#### `task_name` (required)
+#### `task_name` (optional)
 
 **Type:** String  
-**Purpose:** Identifies the task for selection via command line
+**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.
 
 **Example:**
 ```yaml
@@ -42,48 +44,66 @@ task_name: fix-bug
 
 **Usage:**
 ```bash
+# Task is matched by filename "fix-bug.md", not by task_name field
 coding-context /fix-bug
 ```
 
-#### `language` (optional, standard field)
+**Note:** The `task_name` field is optional. If omitted, the task is still matched by its filename.
+
+#### `languages` (optional, standard field)
 
-**Type:** String or Array  
-**Purpose:** Specifies the programming language(s) and automatically filters rules with matching language selector
+**Type:** Array (recommended) or String  
+**Purpose:** Metadata field that specifies the programming language(s) for the task. This field does NOT filter rules - it is metadata only and appears in the task frontmatter output.
 
-The `language` field is a **standard frontmatter field** that acts as a default selector. When a task specifies a language, only rules with that same language value (or no language field) will be included in the context.
+The `languages` field is a **standard frontmatter field** that provides metadata about which programming language(s) the task relates to. Unlike selectors, this field does not automatically filter rules. To filter rules by language, use the `selectors` field or the `-s languages=go` command-line flag.
 
-**Example (single language):**
+**Recommended format (array with lowercase values):**
 ```yaml
 ---
 task_name: implement-feature
-language: go
+languages:
+  - go
 ---
 ```
 
-**Example (multiple languages with OR logic):**
+**Example (multiple languages):**
 ```yaml
 ---
 task_name: polyglot-task
-language:
+languages:
   - go
   - python
   - javascript
 ---
 ```
 
-**Behavior:**
-- Rules with `language: go` are included (when task has `language: go`)
-- Rules without a `language` field are included (generic rules)
-- Rules with different language values are excluded
-- When multiple languages are specified, rules matching ANY of them are included (OR logic)
+**Note:** Both `language` (singular) and `languages` (plural) are accepted in YAML and map to the same field, but `languages` (plural) is recommended. Language values should be lowercase (e.g., `go`, `python`, `javascript`). The field is stored in frontmatter output but does not affect rule filtering.
 
-**Equivalent command-line usage:**
+**To filter rules by language, use selectors:**
+
+**Important distinction:**
+- Frontmatter metadata field: `languages:` (plural) - does NOT filter rules
+- Selector key: `languages:` (plural) - used for filtering rules
+
+**In task frontmatter selectors:**
+```yaml
+---
+task_name: implement-feature
+selectors:
+  languages: go
+---
+```
+
+**On the command line:**
 ```bash
-# These are equivalent:
-coding-context /implement-feature  # (task has language: go)
-coding-context -s language=go /implement-feature
+coding-context -s languages=go /implement-feature
 ```
 
+**Note:** 
+- Use `-s languages=go` (selector flag, plural `languages`)
+- Do NOT use `-p languages=go` (`-p` is for parameter substitution, not filtering)
+- Language values should be lowercase (e.g., `go`, `python`, `javascript`)
+
 #### `single_shot` (optional, standard field)
 
 **Type:** Boolean  
@@ -227,20 +247,20 @@ The `selectors` field allows a task to specify which rules should be included wh
 ---
 task_name: implement-feature
 selectors:
-  language: go
+  languages: go
   stage: implementation
 ---
 ```
 
 **Usage:**
 ```bash
-# Automatically includes rules with language=go AND stage=implementation
+# Automatically includes 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
 ```
 
 **OR Logic with Arrays:**
@@ -251,21 +271,21 @@ You can specify multiple values for the same key using YAML arrays for OR logic:
 ---
 task_name: test-code
 selectors:
-  language: [Go, Python, JavaScript]
+  languages: [go, python, javascript]
   stage: testing
 ---
 ```
 
-This matches rules where `(language=go OR language=python OR language=javascript) AND stage=testing`.
+This matches rules where `(languages=go OR languages=python OR languages=javascript) AND stage=testing`.
 
 **Combining with Command-Line Selectors:**
 
 Selectors from the task frontmatter and command-line `-s` flags are combined (additive):
 
 ```bash
-# Task frontmatter has: selectors.language = Go
+# Task frontmatter has: selectors.languages = go
 # Command line adds: -s priority=high
-# Result: Rules must match language=go AND priority=high
+# Result: Rules must match languages=go AND priority=high
 coding-context -s priority=high /implement-feature
 ```
 
@@ -316,7 +336,7 @@ Task files must be in one of these directories:
 - `./.opencode/command/`
 - `~/.agents/tasks/`
 
-The filename itself doesn't matter if `task_name` is specified in frontmatter. If `task_name` is not specified, the filename (without `.md` extension) is used as the task name.
+Tasks are matched by filename (without `.md` extension). The `task_name` field in frontmatter is optional and used only for metadata. For example, a file named `fix-bug.md` is matched by the command `/fix-bug`, regardless of whether it has `task_name` in its frontmatter.
 
 ## Rule Files
 
@@ -367,32 +387,37 @@ task_name:
 - Rules without `task_name` are included for all tasks (generic rules)
 - The task's own `task_name` is automatically added as a selector
 
-#### `language` (rule selector)
+#### `language` or `languages` (rule selector)
 
-Specifies which programming language(s) this rule applies to. Can be a string or array.
+Specifies which programming language(s) this rule applies to. Can be a string or array. Language values should be lowercase. The recommended format is `languages:` (plural) with an array.
 
+**Recommended format (array):**
 ```yaml
 ---
-language: go
+languages:
+  - go
 ---
-# This rule only applies when language=go is selected
+# This rule only applies when languages=go is selected
 ```
 
 **Multiple languages (OR logic):**
 ```yaml
 ---
-language:
-  - Go
-  - Python
-  - JavaScript
+languages:
+  - go
+  - python
+  - javascript
 ---
 # This rule applies to any of these languages
 ```
 
 **Behavior:**
-- When a task has `language: go`, rules with `language: go` are included
-- Rules without `language` are included (generic rules)
-- Can also be filtered via `-s language=go` command-line flag
+- Rules with `languages: [ go ]` are included when `-s languages=go` is specified (or via task `selectors.languages`)
+- Rules without `languages` are included (generic rules)
+- The task's `languages` field (metadata) does NOT automatically filter rules - use `selectors.languages` or `-s languages=go` instead
+- Language values should be lowercase (e.g., `go`, `python`, `javascript`)
+- Both `language` (singular) and `languages` (plural) are accepted in frontmatter, but `languages` (plural) with array format is recommended
+- **Important:** When using selectors (`-s` flag or `selectors:` in frontmatter), use `languages` (plural) as the key
 
 #### `agent` (rule selector)
 
@@ -427,7 +452,8 @@ mcp_servers:
 **Other common fields:**
 ```yaml
 ---
-language: go
+languages:
+  - go
 stage: implementation
 priority: high
 team: backend
@@ -436,6 +462,8 @@ task_name: implement-feature
 ---
 ```
 
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`). Use `languages:` (plural) with array format.
+
 ### Supported Extensions
 
 - `.md` - Markdown files
@@ -521,7 +549,8 @@ boolean_key: true
 ```yaml
 # ✅ Supported
 ---
-language: go
+languages:
+  - go
 stage: testing
 ---
 
@@ -536,7 +565,7 @@ metadata:
 **Selectors match top-level only:**
 ```bash
 # Works with top-level fields
-coding-context -s language=go /fix-bug
+coding-context -s languages=go /fix-bug
 
 # Doesn't work with nested fields
 coding-context -s metadata.language=go /fix-bug  # Won't match
@@ -550,7 +579,8 @@ Frontmatter values are treated as strings for matching:
 ---
 priority: 1
 enabled: true
-language: go
+languages:
+  - go
 ---
 ```
 
@@ -558,7 +588,7 @@ language: go
 # All values are matched as strings
 coding-context -s priority=1 /task       # Matches priority: 1
 coding-context -s enabled=true /task     # Matches enabled: true
-coding-context -s language=go /task      # Matches language: go
+coding-context -s languages=go /task      # Matches languages: [ go ]
 ```
 
 ## Special Behaviors
@@ -603,8 +633,8 @@ coding-context -s resume=true /fix-bug        # Includes rules
 ## Validation
 
 The CLI validates:
-- ✅ Task files have `task_name` in frontmatter
-- ✅ YAML frontmatter is well-formed
+- ✅ Task files match by filename (`.md` files with matching base name)
+- ✅ YAML frontmatter is well-formed (if present)
 - ✅ At most one task matches the selectors
 
 The CLI does NOT validate:
diff --git a/docs/reference/search-paths.md b/docs/reference/search-paths.md
index 5160673d..2d5aed66 100644
--- a/docs/reference/search-paths.md
+++ b/docs/reference/search-paths.md
@@ -27,8 +27,9 @@ Within each directory, task files are searched in the following locations:
 ### Discovery Rules
 
 - All `.md` files in these directories are examined
-- If `task_name` is present in frontmatter, it's used for task identification
-- If `task_name` is absent, the filename (without `.md` extension) is used as the task name
+- Tasks are matched by filename (without `.md` extension), not by `task_name` in frontmatter
+- The `task_name` field in frontmatter is optional and used only for metadata
+- If multiple files have the same filename, selectors are used to choose between them
 - First match wins (unless selectors create ambiguity)
 - Searches stop when a matching task is found
 - Directories are searched in the order they appear in `-d` flags, then the automatically-added working directory and home directory
@@ -37,16 +38,16 @@ Within each directory, task files are searched in the following locations:
 
 ```
 Project structure:
-./.agents/tasks/fix-bug.md            (task_name: fix-bug)
-./.opencode/command/review-code.md    (task_name: review-code)
-./.opencode/command/deploy.md         (no task_name, uses filename)
-~/.agents/tasks/code-review.md        (task_name: code-review)
+./.agents/tasks/fix-bug.md            (matched by filename "fix-bug")
+./.opencode/command/review-code.md    (matched by filename "review-code")
+./.opencode/command/deploy.md         (matched by filename "deploy")
+~/.agents/tasks/code-review.md        (matched by filename "code-review")
 
 Commands:
-coding-context fix-bug          → Uses ./.agents/tasks/fix-bug.md (from working directory)
-coding-context review-code      → Uses ./.opencode/command/review-code.md (from working directory)
-coding-context deploy           → Uses ./.opencode/command/deploy.md (from working directory)
-coding-context code-review      → Uses ~/.agents/tasks/code-review.md (from home directory)
+coding-context /fix-bug          → Uses ./.agents/tasks/fix-bug.md (from working directory)
+coding-context /review-code      → Uses ./.opencode/command/review-code.md (from working directory)
+coding-context /deploy           → Uses ./.opencode/command/deploy.md (from working directory)
+coding-context /code-review      → Uses ~/.agents/tasks/code-review.md (from home directory)
 ```
 
 **Note:** The working directory and home directory are automatically added to search paths, so tasks in those locations are found automatically.
@@ -219,7 +220,7 @@ Regardless of where rules are found, they can be filtered using selectors:
 
 ```bash
 # Include only Go rules (from any location)
-coding-context -s language=Go fix-bug
+coding-context -s languages=go /fix-bug
 
 # Include only planning rules
 coding-context -s stage=planning plan-feature
@@ -233,16 +234,18 @@ coding-context -s stage=planning plan-feature
 .agents/
 └── rules/
     ├── general-standards.md        (no frontmatter - always included)
-    ├── go-backend.md               (language: Go)
-    ├── python-ml.md                (language: Python)
-    └── javascript-frontend.md      (language: JavaScript)
+    ├── go-backend.md               (languages: [ go ])
+    ├── python-ml.md                (languages: [ python ])
+    └── javascript-frontend.md      (languages: [ javascript ])
 
 Commands:
-coding-context -s language=Go fix-bug
+coding-context -s languages=go /fix-bug
   → Includes: general-standards.md, go-backend.md
 
-coding-context -s language=Python train-model
+coding-context -s languages=python /train-model
   → Includes: general-standards.md, python-ml.md
+
+**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`).
 ```
 
 ### Environment Tiers
@@ -286,9 +289,10 @@ coding-context -s team=backend fix-bug
 
 **Task not found:**
 - Verify that `.agents/tasks/`, `.agents/commands/`, `.cursor/commands/`, or `.opencode/command/` directory exists in one of the search path directories
-- Check `task_name` field in frontmatter matches the task name you're using
+- Check that the filename (without `.md` extension) matches the task name you're using (e.g., `fix-bug.md` for `/fix-bug`)
 - Ensure filename has `.md` extension
 - Verify the directory containing the task is in search paths (working directory and home directory are added automatically)
+- Note: Tasks are matched by filename, not by `task_name` in frontmatter
 
 **Rules not filtered correctly:**
 - Verify frontmatter YAML is valid
diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md
index 794c67d6..2b2956a7 100644
--- a/docs/tutorials/getting-started.md
+++ b/docs/tutorials/getting-started.md
@@ -84,7 +84,8 @@ EOF
 ```
 
 **What this does:**
-- The frontmatter (`---` section) defines `task_name: fix-bug` which is how you'll reference this task
+- 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 `${issue_key}` and `${description}` are placeholders that will be replaced with actual values
 - The content provides instructions for the AI agent
 
@@ -95,7 +96,8 @@ Rules are reusable context snippets that provide guidelines to AI agents.
 ```bash
 cat > rules/coding-standards.md << 'EOF'
 ---
-language: Go
+languages:
+  - go
 ---
 
 # Go Coding Standards
@@ -110,8 +112,9 @@ EOF
 ```
 
 **What this does:**
-- The frontmatter includes `language: Go`, which allows filtering this rule for Go projects
+- The frontmatter includes `languages: [ go ]`, which allows this rule to be filtered when using `-s languages=go`
 - The content provides coding standards that the AI agent should follow
+- **Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`). Use `languages:` (plural) with array format.
 
 ## Step 5: Assemble Context
 
@@ -125,15 +128,16 @@ cd ..
 coding-context \
   -p issue_key=BUG-123 \
   -p description="Application crashes on startup" \
-  -s language=Go \
+  -s languages=go \
   /fix-bug
 ```
 
 **What this command does:**
 - `-p issue_key=BUG-123` replaces `${issue_key}` in the task
 - `-p description="..."` replaces `${description}` in the task
-- `-s language=Go` includes only rules with `language: Go` in frontmatter
+- `-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`)
 
 You should see output containing:
 1. The Go coding standards rule
@@ -147,7 +151,7 @@ Pipe the output to an AI agent:
 coding-context \
   -p issue_key=BUG-123 \
   -p description="Application crashes on startup" \
-  -s language=Go \
+  -s languages=go \
   /fix-bug | llm -m claude-3-5-sonnet-20241022
 ```
 
@@ -163,7 +167,7 @@ coding-context \
   -d git::https://github.com/company/shared-coding-rules.git \
   -p issue_key=BUG-123 \
   -p description="Application crashes on startup" \
-  -s language=Go \
+  -s languages=go \
   /fix-bug | llm -m claude-3-5-sonnet-20241022
 ```