disable lagacy overrides

.agents/README.md

@@ -0,0 +1,59 @@
+# Doc agents
+
+We use two types of documentation agents: a generic AI agent, which serves as the default tool for product teams without a writer and handles the basic, standardized workflow; and the AI twin, a personalized agent that encodes your unique research, structure, writing, and review process. The generic agent fills the gap when no writer is available, while the AI twin amplifies your individual craft and raises the quality bar for the teams you support.
+
+Both types of doc agent are designed to help you generate, update, and maintain documentation across any Grafana project. They guide you through the entire documentation workflow—from understanding the product to drafting, reviewing, and preparing PRs—or you can run them at any individual stage you choose. They build structure, create and update content, validate links, and surface issues, while you stay in control of what to approve, refine, or publish.
+
+This guide explains what each agent does within the documentation workflow and what responsibilities remain with you as the writer.
+
+## What you do (as the writer)
+
+The agents are installed in your project.
+
+Use the agent directly in VS Code with any AI model. Tell Copilot, for example, “Run brenda_agent.md using style-guide.md.” You can run the full workflow from start to finish, or jump into a specific stage—Teacher, Information Architect, Author, Reviewer, or Committer—depending on the task you’re working on.
+
+Your workflow as a writer is:
+
+- Run the agent files
+- Answer yes/no questions from the agent
+- Review the drafts it produces
+- Approve or edit the content
+- Decide when to commit a PR
+
+The agent does everything else automatically.
+
+## What the agents do
+
+Once the agent is installed into your project, it takes you through the entire documentation workflow.
+
+You can run it in its entirely, or run a specific stage of it.
+
+### Teach you about the product
+Helps you quickly understand a new product area by explaining its purpose, concepts, terminology, user journeys, workflows, and system behavior, while flagging uncertainties before moving on to the next stage.
+
+###  Determine what needs documenting
+It scans changes or your whole repository to understand what should be added or updated.
+
+### Create your documentation structure
+It builds folders, section index pages, and introduction pages based on the context.
+
+###  Write new docs or edit existing documentation
+The agent can draft:
+- Get started pages
+- Setup guides
+- Configuration pages
+- Concepts
+- Task/guide documentation
+
+You can choose to generate all pages or just specific sections.
+
+###  Review your documentation
+It checks:
+- internal links
+- folder structure
+- formatting
+- style rules
+
+###  Prepare a pull request
+It writes the PR title and summary, increments version numbers, and prepares changes for you to review.
+

.agents/doc-agents/shared/README.md

@@ -0,0 +1,157 @@
+# Documentation Agent Shared Resources
+
+This directory contains shared resources for documentation agents and writers working on Tempo documentation.
+
+## Files Overview
+
+### [`style-guide.md`](style-guide.md)
+**Purpose**: Grafana documentation style guide and templates
+
+**When to use**: 
+- Before writing any documentation
+- When reviewing documentation for style compliance
+- When unsure about formatting, phrasing, or structure
+
+**Key contents**:
+- Style rules (tense, voice, formatting)
+- Template structures (concept, task, reference, scenario)
+- Common style requirements
+
+### [`best-practices.md`](best-practices.md)
+**Purpose**: Best practices learned from documentation work
+
+**When to use**:
+- Starting a new documentation task
+- Reviewing documentation before submission
+- Learning from past documentation work
+- Avoiding common pitfalls
+
+**Key contents**:
+- Pre-writing checklist
+- Verification process
+- Common pitfalls and solutions
+- Documentation patterns (good vs. bad)
+- Guidelines for addressing user confusion
+
+### [`verification-checklist.md`](verification-checklist.md)
+**Purpose**: Comprehensive checklist for verifying documentation accuracy
+
+**When to use**:
+- Before submitting documentation changes
+- When updating existing documentation
+- To ensure completeness and accuracy
+- As a quality assurance step
+
+**Key contents**:
+- Codebase verification steps
+- Configuration reference checks
+- Version compatibility verification
+- Style guide compliance
+- Example quality checks
+
+### [`release-notes-workflow.md`](release-notes-workflow.md)
+**Purpose**: Workflow for creating Grafana Tempo release notes
+
+**When to use**:
+- Creating release notes for a new Tempo version
+- Reviewing or updating existing release notes
+- Understanding the multi-phase release notes process
+- Looking up the document structure template or example prompts
+
+**Key contents**:
+- Multi-phase workflow (input gathering, documentation assessment, gap resolution, categorization, writing, validation, polish)
+- Documentation assessment process for evaluating whether PRs need docs and whether those docs exist
+- PR classification system (docs present, docs needed, docs update needed, no docs required)
+- Document structure template with frontmatter and section layout
+- Example prompts for common release notes tasks (initial draft, PR deep dive, documentation assessment, upgrade considerations)
+- Tempo-specific style guidelines and conventions
+- Iteration checklist for content completeness, documentation assessment, documentation coverage, and quality
+- Feature-by-feature deep dive workflow for complex releases
+
+### [`metrics-generator-knowledge.md`](metrics-generator-knowledge.md)
+**Purpose**: Domain-specific knowledge about Tempo metrics-generator
+
+**When to use**:
+- Writing or updating metrics-generator documentation
+- Understanding feature scope (span-metrics vs. service-graphs)
+- Verifying configuration options
+- Understanding user confusion points
+
+**Key contents**:
+- Feature scope (processor-specific vs. shared)
+- Configuration structure examples
+- Common user confusion points
+- Version compatibility notes
+- Key code file locations
+
+## Usage Workflow
+
+### For New Documentation
+
+1. **Start with** [`style-guide.md`](style-guide.md) to understand formatting requirements
+2. **Review** [`best-practices.md`](best-practices.md) for common patterns and pitfalls
+3. **Reference** [`metrics-generator-knowledge.md`](metrics-generator-knowledge.md) if working on metrics-generator features
+4. **Use** [`verification-checklist.md`](verification-checklist.md) before submitting
+
+### For Release Notes
+
+1. **Follow** [`release-notes-workflow.md`](release-notes-workflow.md) for the complete multi-phase process
+2. **Use** [`docs-pr-check` skill](../../../.claude/skills/docs-pr-check/SKILL.md) for documentation assessment (Phase 1.5)
+3. **Use** [`docs-pr-write` skill](../../../.claude/skills/docs-pr-write/SKILL.md) for documentation gap resolution (Phase 1.75)
+4. **Reference** [`style-guide.md`](style-guide.md) for general style rules
+5. **Use** [`verification-checklist.md`](verification-checklist.md) before submitting
+
+### For Updating Existing Documentation
+
+1. **Check** [`verification-checklist.md`](verification-checklist.md) to ensure all areas are covered
+2. **Reference** [`best-practices.md`](best-practices.md) for common issues to avoid
+3. **Verify** against [`metrics-generator-knowledge.md`](metrics-generator-knowledge.md) if updating metrics-generator docs
+4. **Review** [`style-guide.md`](style-guide.md) for consistency
+
+### For Addressing GitHub Issues
+
+1. **Read** [`best-practices.md`](best-practices.md) section on "Addressing User Confusion"
+2. **Check** [`metrics-generator-knowledge.md`](metrics-generator-knowledge.md) for known confusion points
+3. **Follow** [`verification-checklist.md`](verification-checklist.md) to ensure fixes are complete
+4. **Verify** against [`style-guide.md`](style-guide.md) for consistency
+
+## Quick Reference
+
+| Task | Primary Resource | Secondary Resource |
+|------|-----------------|-------------------|
+| Starting new docs | `style-guide.md` | `best-practices.md` |
+| Updating docs | `verification-checklist.md` | `best-practices.md` |
+| Writing release notes | `release-notes-workflow.md` | `style-guide.md` |
+| PR docs assessment (triage) | `../../../.claude/skills/docs-pr-check/SKILL.md` | `release-notes-workflow.md` |
+| PR docs writing (execution) | `../../../.claude/skills/docs-pr-write/SKILL.md` | `release-notes-workflow.md` |
+| Metrics-generator work | `metrics-generator-knowledge.md` | `verification-checklist.md` |
+| Fixing user issues | `best-practices.md` | `metrics-generator-knowledge.md` |
+| Style questions | `style-guide.md` | `best-practices.md` |
+| Pre-submission review | `verification-checklist.md` | `style-guide.md` |
+
+## Maintenance
+
+These files should be updated when:
+- New patterns or best practices are discovered
+- Common issues are identified and resolved
+- Domain knowledge expands (new features, new confusion points)
+- Style guide is updated
+- Verification processes improve
+
+## Contributing
+
+When you discover new insights:
+1. Document them in the appropriate file
+2. Update the relevant sections
+3. Add examples if helpful
+4. Share with the team
+
+## Related Resources
+
+- Main documentation: `docs/sources/tempo/`
+- Configuration reference: `docs/sources/tempo/configuration/_index.md`
+- Codebase: `modules/generator/processor/`
+- CHANGELOG: `CHANGELOG.md`
+- Skills workflow README: `.claude/skills/README.md`
+- Skill: `.claude/skills/docs-pr-check/SKILL.md`
+- Skill: `.claude/skills/docs-pr-write/SKILL.md`

.agents/doc-agents/shared/best-practices.md

@@ -0,0 +1,135 @@
+# Documentation Best Practices
+
+> **For human writers only.** Do not include this file in agent or skill instructions. It is reference material for people, not a task list for agents.
+
+This guide captures best practices learned from documentation work, particularly around verifying accuracy, addressing user confusion, and maintaining consistency.
+
+## Pre-Writing Checklist
+
+Before writing or updating documentation:
+
+- [ ] Identify the user problem or confusion point (e.g., GitHub issues)
+- [ ] Locate the relevant codebase implementation
+- [ ] Check the configuration reference documentation
+- [ ] Review related documentation for consistency
+- [ ] Understand feature scope (what's processor-specific vs. shared)
+
+## Verification Process
+
+Always verify documentation against multiple sources:
+
+### 1. Codebase Verification
+- Read the actual implementation code
+- Verify feature names, configuration options, and behavior
+- Check for default values and optional parameters
+- Understand the relationship between features
+
+### 2. Configuration Reference Check
+- Compare documented configuration options with `docs/sources/tempo/configuration/_index.md`
+- Ensure all options are documented consistently
+- Verify YAML structure and examples match the reference
+
+### 3. Version Compatibility
+- Check CHANGELOG.md for when features were introduced
+- Verify feature availability in target version (e.g., 2.10 vs. 3.0)
+- Note any version-specific behavior or requirements
+
+### 4. Style Guide Compliance
+- Review against `.agents/doc-agents/shared/style-guide.md`
+- Check for "see" vs "refer to" usage
+- Verify heading structure and introductions
+- Ensure examples use proper phrasing
+
+## Common Pitfalls to Avoid
+
+### 1. Confusing Examples
+**Problem**: Examples that show default behavior instead of the feature's purpose
+- **Bad**: Showing `deployment.environment` → `deployment_environment` (default sanitization)
+- **Good**: Showing `deployment.environment` → `env` (actual renaming)
+
+**Solution**: Always test examples to ensure they demonstrate the intended use case
+
+### 2. Missing Clarifications
+**Problem**: Assuming users understand implicit requirements
+- **Bad**: Not explaining that `source_labels` must use original attribute names
+- **Good**: Explicitly stating "must contain original span or resource attribute names (with dots)"
+
+**Solution**: Add admonitions or explicit notes for non-obvious requirements
+
+### 3. Unclear Feature Relationships
+**Problem**: Not explaining how related features interact
+- **Bad**: Listing `dimensions` and `dimension_mappings` without explaining they're alternatives
+- **Good**: Explaining when to use each and that they're alternatives, not complementary
+
+**Solution**: Add "Understanding X vs Y" sections for related features
+
+### 4. Inaccurate Statements
+**Problem**: Stating incorrect information (e.g., "two metrics" when there are three)
+- **Solution**: Always verify against codebase, especially for counts, lists, and defaults
+
+### 5. Missing Feature Documentation
+**Problem**: Not documenting features that exist in code but aren't in docs
+- **Solution**: Cross-reference codebase with documentation to find gaps
+
+## Documentation Patterns
+
+### Good Patterns
+
+**Clear Introductions After Headings**
+```markdown
+### Disabling intrinsic dimensions
+
+You can control which intrinsic dimensions are included in your metrics. Disable any of the default intrinsic dimensions using the `intrinsic_dimensions` configuration.
+```
+
+**Explicit Clarifications**
+```markdown
+{{< admonition type="note" >}}
+The `source_labels` field must contain the **original span or resource attribute names** (with dots), not sanitized Prometheus label names.
+{{< /admonition >}}
+```
+
+**Prose Over Lists for Explanations**
+```markdown
+Use `dimensions` when you want to add span attributes as labels using their default (sanitized) names. Use `dimension_mappings` when you want to rename attributes to custom label names or combine multiple attributes.
+```
+
+**Proper Example Phrasing**
+```markdown
+The following example shows how to rename the `deployment.environment` attribute to a shorter label called `env`, for example:
+```
+
+### Patterns to Avoid
+
+**Vague References**
+- ❌ "see below"
+- ✅ "as described in the sections below" or "refer to the sections below"
+
+**Passive Voice**
+- ❌ "This processor mirrored the implementation"
+- ✅ "This processor mirrors the implementation"
+
+**Lists as Paragraph Substitutes**
+- ❌ Using bullet lists for explanatory content
+- ✅ Using prose paragraphs for explanations
+
+## Addressing User Confusion
+
+When addressing GitHub issues or user feedback:
+
+1. **Identify Root Cause**: Understand what's actually confusing, not just the symptom
+2. **Verify Against Code**: Ensure the documentation matches actual behavior
+3. **Add Clarifications**: Don't just fix examples—add explicit guidance
+4. **Explain Relationships**: Help users understand how features relate
+5. **Provide Clear Examples**: Show actual use cases, not edge cases
+
+## Review Process
+
+Before submitting documentation, use [`verification-checklist.md`](verification-checklist.md).
+
+## Continuous Improvement
+
+- Review GitHub issues for documentation gaps
+- Cross-reference codebase changes with documentation
+- Update knowledge base when discovering new patterns
+- Share learnings with the documentation team