Trim AGENTS.md to agent-specific rules

ARCHITECTURE.md

@@ -362,4 +362,4 @@ When Medium changes UI:
 5. Re-capture fixtures
 6. Run tests
 
-See main AGENTS.md for full debugging workflow.
+See README.md for the full debugging workflow.

CONTRIBUTING.md

@@ -33,8 +33,8 @@ See [Pull Request Best Practices](./docs/best-practices/PULL_REQUESTS.md) for co
 ### Reporting Issues
 
 - **Bug Reports**: Use GitHub Issues with detailed reproduction steps, error logs, and environment details
-- **Feature Requests**: Describe the use case and expected behavior, assess fragility risks (see AGENTS.md)
-- **Questions**: Check existing issues and AGENTS.md first, then open a discussion
+- **Feature Requests**: Describe the use case and expected behavior, assess fragility risks (see Fragility Assessment below)
+- **Questions**: Check existing issues and README.md/CONTRIBUTING.md first, then open a discussion
 
 ### Development Setup
 
@@ -72,7 +72,7 @@ See [Pull Request Best Practices](./docs/best-practices/PULL_REQUESTS.md) for co
 
 - Check existing issues and PRs to avoid duplication
 - For major changes, open an issue first to discuss the approach
-- **Read AGENTS.md thoroughly** - contains essential project context and patterns
+- **Read README.md for project context** and **AGENTS.md for agent rules**
 - Review relevant best practices in `docs/best-practices/`
 - **AI Agents**: Always use EnterPlanMode for non-trivial changes before implementing
 
@@ -171,7 +171,7 @@ See [Pull Request Best Practices - Definition of Done](./docs/best-practices/PUL
 **Medium MCP Server additions**:
 
 ### Documentation (Project-Specific)
-- [ ] **AGENTS.md** updated if selectors, tools, or workflows changed
+- [ ] **AGENTS.md** updated if agent-specific rules changed
 - [ ] **README.md** updated if user-facing behavior changed
 - [ ] **ARCHITECTURE.md** updated if technical implementation changed
 - [ ] **CHANGELOG.md** entry added in `[Unreleased]` section
@@ -221,7 +221,7 @@ See [Pull Request Best Practices - PR Review Checklist](./docs/best-practices/PU
 - **Fixture Updates**: After selector fixes (`scripts/utils/capture-fixtures.ts`)
 - **Error Handling**: Better error messages with actionable context
 - **Test Coverage**: Add missing unit/integration tests
-- **Documentation**: Update AGENTS.md with new selectors/patterns
+- **Documentation**: Update README.md/CONTRIBUTING.md with new selectors or workflows
 
 **Medium Impact**:
 - **Performance**: Reduce browser launch overhead
@@ -241,7 +241,7 @@ See [Pull Request Best Practices - PR Review Checklist](./docs/best-practices/PU
 ## 💬 Getting Help
 
 **Stuck on Something?**
-- **Read AGENTS.md first** - contains debugging workflows and debug scripts
+- **Read README.md first** for debugging workflows and script references
 - Check `docs/best-practices/` for logging, testing, TypeScript, PR workflow
 - Look at existing code for patterns (e.g., similar tool implementations)
 - Run debug scripts in `scripts/debug/` to understand selector issues
@@ -296,7 +296,7 @@ npx ts-node scripts/test/test-session-flow.ts          # Test session management
 
 ### Key Documentation
 
-- **[AGENTS.md](./AGENTS.md)** - Developer guide, debugging workflows, selectors
+- **[AGENTS.md](./AGENTS.md)** - AI agent rules of engagement
 - **[README.md](./README.md)** - User-facing features and setup
 - **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Technical implementation details
 - **[docs/best-practices/](./docs/best-practices/)** - Universal guidelines
@@ -311,7 +311,7 @@ Your contributions help make AI-powered content publishing more accessible to de
 
 **For AI Agents**:
 - Follow this guide strictly
-- Reference AGENTS.md for project context
+- Reference README.md/ARCHITECTURE.md for project context and AGENTS.md for agent rules
 - Read [Pull Request Best Practices](./docs/best-practices/PULL_REQUESTS.md) for workflow
 - Read [docs/best-practices/DOCUMENTATION.md](./docs/best-practices/DOCUMENTATION.md) for documentation structure
 - Use EnterPlanMode for planning

README.md

@@ -364,10 +364,44 @@ tail -100 ~/Library/Logs/Claude/mcp*.log | grep -i error
 - **Browser doesn't close after login** (Fixed in v1.2): Update to latest version - Medium changed their UI selectors
 - **Session file not created**: Ensure you complete the full login (see profile icon appear)
 - **Debug login detection**: Run `npx ts-node scripts/debug/debug-login.ts` to analyze current page selectors
-- **Current selectors (v1.2)**:
-  - User icon: `[data-testid="headerUserIcon"]`
-  - Write button: `[data-testid="headerWriteButton"]`
-  - Notifications: `[data-testid="headerNotificationButton"]`
+- **Selector reference**: See [Selector Reference (v1.3+)](#selector-reference-v13) for current fallback selectors
+
+### Selector Reference (v1.3+)
+
+**Login Indicators**:
+```typescript
+'[data-testid="headerUserIcon"]'
+'[data-testid="headerWriteButton"]'
+'[data-testid="headerNotificationButton"]'
+'button[aria-label*="user"]'
+```
+
+**Article List**:
+```typescript
+'table tbody tr'  // Container
+'h2'              // Title
+'a[href*="/p/"][href*="/edit"]'  // Draft links
+'a[href*="/@"]'   // Published links
+```
+
+**Article Editor**:
+```typescript
+'[data-testid="editorTitleParagraph"]'   // Title field
+'[data-testid="editorParagraphText"]'    // Content field
+```
+
+**Reading Lists**:
+```typescript
+'[data-testid="readingList"]'   // Primary
+'a[href*="/list/"]'             // Fallback
+```
+
+**Feed Articles**:
+```typescript
+'article'                        // Container
+'[data-testid="story-preview"]'  // Alternative container
+'h1', 'h2', 'h3'                // Title
+```
 
 ### Article Retrieval Issues (v1.2+)
 - **`get-my-articles` returns 0 articles**: Medium changed from card layout to table layout
@@ -396,7 +430,7 @@ When Medium updates their website, selectors break. Here's how to fix them:
 5. **Run the corresponding test** to verify the fix
 6. **Re-capture fixtures**: `npx ts-node scripts/utils/capture-fixtures.ts`
 7. **Run fixture-based tests**: `npm run test:unit -- tests/integration/`
-8. **Update documentation** (README.md, AGENTS.md) with new selectors
+8. **Update documentation** (README.md, CONTRIBUTING.md) with new selectors or workflows
 
 #### Debug Scripts by Functionality
 
@@ -555,7 +589,7 @@ medium-mcp-server/
 ├── tsconfig.json                     # TypeScript configuration
 ├── jest.config.js                    # Jest test configuration
 ├── playwright.config.ts              # Playwright E2E configuration
-├── AGENTS.md                         # AI assistant guidance (universal)
+├── AGENTS.md                         # AI agent rules of engagement
 ├── CLAUDE.md                         # Pointer to AGENTS.md
 ├── ARCHITECTURE.md                   # Technical deep-dive (detailed)
 ├── CONTRIBUTING.md                   # Contribution guidelines

docs/README.md

@@ -20,7 +20,7 @@ Comprehensive documentation for Medium MCP Server.
 
 **Essential Reading**:
 - [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines, PR process
-- [AGENTS.md](../AGENTS.md) - Complete project guide (for AI agents and developers)
+- [AGENTS.md](../AGENTS.md) - AI agent rules of engagement
 - [ARCHITECTURE.md](../ARCHITECTURE.md) - Technical architecture, design decisions
 
 **Architecture Decision Records** (Why Decisions Were Made):
@@ -49,17 +49,16 @@ See [best-practices/README.md](./best-practices/README.md) for overview.
 
 ### Testing
 - [Testing Best Practices](./best-practices/TESTING.md) - Multi-layered testing strategy
-- [AGENTS.md](../AGENTS.md#testing-strategy) - Project-specific test organization
+- [CONTRIBUTING.md](../CONTRIBUTING.md#testing-this-project) - Project-specific test organization
 - [Test Fixtures](../tests/fixtures/README.md) - Fixture-based testing
 
 ### Debugging
-- [AGENTS.md](../AGENTS.md#debugging-workflow) - Complete debugging workflow
+- [README.md](../README.md#medium-ui-changes---debugging-selector-issues) - Complete debugging workflow
 - [Debug Scripts](../scripts/README.md#debug-scripts-when-medium-ui-changes) - Selector debugging tools
-- [Current Selectors](../AGENTS.md#current-selectors) - Selector reference
+- [Current Selectors](../README.md#selector-reference-v13) - Selector reference
 
 ### Architecture
 - [ARCHITECTURE.md](../ARCHITECTURE.md) - System design, component interactions
-- [AGENTS.md](../AGENTS.md#architecture) - Architecture overview
 - [ADRs](./adr/README.md) - Why architectural decisions were made
 
 ### Contributing
@@ -72,17 +71,18 @@ See [best-practices/README.md](./best-practices/README.md) for overview.
 
 ## For AI Agents
 
-**Primary documentation**: [AGENTS.md](../AGENTS.md)
+**Primary documentation**: [AGENTS.md](../AGENTS.md) (rules) + [README.md](../README.md) (context)
 
 **Documentation structure**: [best-practices/DOCUMENTATION.md](./best-practices/DOCUMENTATION.md) - Documentation organization best practices
 
 **Before making changes**:
-1. Read AGENTS.md thoroughly
-2. Review relevant best practices in `best-practices/`
-3. **Read ADRs** in `adr/` to understand why decisions were made
-4. Use EnterPlanMode for non-trivial changes
-5. Follow contribution guidelines in CONTRIBUTING.md
-6. **Create new ADRs** for significant architectural decisions
+1. Read AGENTS.md (agent rules)
+2. Read README.md for project context
+3. Review relevant best practices in `best-practices/`
+4. **Read ADRs** in `adr/` to understand why decisions were made
+5. Use EnterPlanMode for non-trivial changes
+6. Follow contribution guidelines in CONTRIBUTING.md
+7. **Create new ADRs** for significant architectural decisions
 
 ---
 
@@ -92,12 +92,12 @@ See [best-practices/README.md](./best-practices/README.md) for overview.
 
 | Change Type | Update These Docs |
 |-------------|-------------------|
-| New MCP tool | README.md, AGENTS.md, CHANGELOG.md |
-| Selector update | AGENTS.md (Current Selectors section) |
-| Architecture change | ARCHITECTURE.md, AGENTS.md |
+| New MCP tool | README.md, CHANGELOG.md |
+| Selector update | README.md |
+| Architecture change | ARCHITECTURE.md, README.md |
 | New best practice | docs/best-practices/, CONTRIBUTING.md |
 | Breaking change | CHANGELOG.md (with migration guide) |
 | Bug fix | CHANGELOG.md |
-| Debug script added | scripts/README.md, AGENTS.md |
+| Debug script added | scripts/README.md, README.md |
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md#changelog-maintenance) for CHANGELOG update guidelines.

docs/best-practices/PULL_REQUESTS.md

@@ -532,7 +532,7 @@ Suggested update for README.md:
 
 Also check:
 - ARCHITECTURE.md session lifecycle section
-- AGENTS.md session management section
+- README.md session management section
 ```
 
 **Bad review comment**:
@@ -830,7 +830,7 @@ For each behavior change, search all documentation:
 
 ```bash
 # Example: Session behavior changed
-grep -r "session" README.md ARCHITECTURE.md AGENTS.md docs/
+grep -r "session" README.md ARCHITECTURE.md docs/
 ```
 
 #### 3. Verify Each Mention
@@ -845,7 +845,7 @@ For each search result:
 Make a checklist:
 - [ ] README.md line 270: "session saved during login" → "session saved after every operation"
 - [ ] ARCHITECTURE.md line 205: Add step "Auto-save after operation"
-- [ ] AGENTS.md line 110: Add "Auto-Update" step
+- [ ] CONTRIBUTING.md: Update any workflow steps that mention session persistence
 
 #### 5. Request Updates or Make Updates
 

docs/best-practices/README.md

@@ -171,20 +171,20 @@ cp docs/best-practices/LOGGING.md ../my-project/docs/
 
 These best practices are **standards**. For project-specific implementations, see:
 
-- [AGENTS.md](../../AGENTS.md) - How Medium MCP Server applies these best practices
+- [README.md](../../README.md) - Project overview and operational workflows
 - [ARCHITECTURE.md](../../ARCHITECTURE.md) - Architecture decisions based on best practices
 - [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution guidelines referencing best practices
 
 **Example**:
 - [TESTING.md](./TESTING.md) defines multi-layered testing strategy (standard)
-- [AGENTS.md](../../AGENTS.md#testing-strategy) shows how Medium MCP Server implements it (149 tests, 4 layers)
+- [CONTRIBUTING.md](../../CONTRIBUTING.md#testing-this-project) shows how Medium MCP Server implements it (149 tests, 4 layers)
 
 ---
 
 ## See Also
 
 - [CONTRIBUTING.md](../../CONTRIBUTING.md) - How to contribute to this project
-- [AGENTS.md](../../AGENTS.md) - Complete project guide
+- [AGENTS.md](../../AGENTS.md) - AI agent rules of engagement
 - [ARCHITECTURE.md](../../ARCHITECTURE.md) - Technical architecture
 - [DOCUMENTATION.md](./DOCUMENTATION.md) - Documentation organization best practices
 

examples/README.md

@@ -114,7 +114,7 @@ After restarting Claude Desktop, the Medium MCP Server should appear in the avai
 ## Additional Resources
 
 - [Main README](../README.md) - Installation and usage guide
-- [AGENTS.md](../AGENTS.md) - Comprehensive development guide
+- [AGENTS.md](../AGENTS.md) - AI agent rules of engagement
 - [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
 - [Troubleshooting Section](../README.md#troubleshooting) - Common debugging steps
 

scripts/README.md

@@ -138,12 +138,12 @@ Use these to manually test functionality after changes.
 5. **Update fixtures**: `npx ts-node scripts/utils/capture-fixtures.ts`
 6. **Run tests**: `npm run test:all`
 
-See [AGENTS.md](../AGENTS.md) debugging workflow section for complete details.
+See [README.md](../README.md#medium-ui-changes---debugging-selector-issues) for complete details.
 
 ---
 
 ## See Also
 
-- [AGENTS.md](../AGENTS.md) - Complete project guide with debugging workflow
+- [README.md](../README.md) - Project overview and debugging workflow
 - [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
 - [ARCHITECTURE.md](../ARCHITECTURE.md) - Technical architecture