agent-docs 1.0.0

package/.cursor/plans/OPTIMISE.md

@@ -0,0 +1,379 @@
+# Optimizing Docs for AI Agents
+
+This plan documents the process for converting high token count documentation
+files into AI Agent-friendly low token versions without losing any essential
+details. This plan is used by AI-powered IDEs (like Cursor) to optimize docs,
+not by the CLI tool itself.
+
+## Core Principles
+
+- **Terse but precise** - Every word counts, no fluff
+- **Tables over prose** - Use tables for structured data
+- **Bullet points for lists** - Use lists for scannability
+- **Minimal code examples** - Only essential examples
+- **Structured sections** - Clear, consistent organization
+- **Reference-style formatting** - Quick reference format
+
+## Optimization Techniques
+
+### Text Reduction Strategies
+
+1. **Remove redundancy:**
+    - Eliminate repeated information
+    - Remove unnecessary explanations
+    - Cut verbose descriptions
+    - Remove filler words and phrases
+
+2. **Use abbreviations:**
+    - Use standard abbreviations where clear
+    - Abbreviate common terms (e.g., "config" for "configuration")
+    - Use symbols where appropriate (e.g., `&` for "and" in tables)
+
+3. **Condense explanations:**
+    - Convert paragraphs to bullet points
+    - Use concise phrasing
+    - Remove examples that don't add value
+    - Focus on actionable information
+
+### Structural Optimizations
+
+#### Prose to Tables
+
+Convert verbose descriptions to tables:
+
+**Before:**
+
+```markdown
+The `enabled` property controls whether the feature is active. It accepts a
+boolean value. The default is `true`. When set to `false`, the feature is
+disabled.
+```
+
+**After:**
+
+```markdown
+| Property | Type    | Default | Description                            |
+| -------- | ------- | ------- | -------------------------------------- |
+| enabled  | boolean | true    | Controls whether the feature is active |
+```
+
+#### Lists to Tables
+
+Convert property lists to tables:
+
+**Before:**
+
+```markdown
+- `name` (string): The name of the item
+- `value` (number): The numeric value
+- `active` (boolean): Whether the item is active
+```
+
+**After:**
+
+```markdown
+| Property | Type    | Description                |
+| -------- | ------- | -------------------------- |
+| name     | string  | The name of the item       |
+| value    | number  | The numeric value          |
+| active   | boolean | Whether the item is active |
+```
+
+#### API Documentation to Tables
+
+Convert API documentation to tables:
+
+**Before:**
+
+```markdown
+## Methods
+
+### `getData(id: string): Promise<Data>`
+
+Retrieves data for the given ID. Returns a Promise that resolves to a Data
+object.
+
+### `setData(id: string, data: Data): Promise<void>`
+
+Sets data for the given ID. Returns a Promise that resolves when complete.
+```
+
+**After:**
+
+```markdown
+## API Reference
+
+| Method    | Parameters               | Returns         | Description                     |
+| --------- | ------------------------ | --------------- | ------------------------------- |
+| `getData` | `id: string`             | `Promise<Data>` | Retrieves data for the given ID |
+| `setData` | `id: string, data: Data` | `Promise<void>` | Sets data for the given ID      |
+```
+
+#### Property Lists to Tables
+
+Convert configuration property lists to tables:
+
+**Before:**
+
+```markdown
+## Configuration
+
+- `outputDir`: The output directory for generated files
+- `format`: The output format (json, yaml, or xml)
+- `verbose`: Enable verbose logging
+```
+
+**After:**
+
+```markdown
+## Configuration
+
+| Property  | Type                      | Default    | Description                          |
+| --------- | ------------------------- | ---------- | ------------------------------------ |
+| outputDir | string                    | `./output` | Output directory for generated files |
+| format    | 'json' \| 'yaml' \| 'xml' | 'json'     | Output format                        |
+| verbose   | boolean                   | false      | Enable verbose logging               |
+```
+
+### Content Organization Patterns
+
+1. **Group related information:**
+    - Organize by topic, not by source
+    - Group similar APIs together
+    - Cluster configuration options by category
+
+2. **Use consistent structure:**
+    - Follow standard doc format (Overview, Configuration, API Reference, etc.)
+    - Maintain consistent section ordering
+    - Use consistent formatting within sections
+
+3. **Prioritize essential information:**
+    - Put most important information first
+    - Move detailed explanations to end
+    - Highlight critical gotchas early
+
+## Step-by-Step Conversion Process
+
+### 1. Analysis
+
+1. **Read the entire doc** to understand structure and content
+2. **Identify optimization opportunities:**
+    - Long paragraphs that can be condensed
+    - Lists that can become tables
+    - API documentation that can be tabularized
+    - Redundant explanations
+    - Verbose examples
+
+3. **Categorize content:**
+    - Essential information (must keep)
+    - Important information (should keep)
+    - Nice-to-have information (can condense)
+    - Redundant information (can remove)
+
+### 2. Structure Planning
+
+1. **Plan section organization:**
+    - Determine optimal section order
+    - Identify sections that can be merged
+    - Plan table structures for each section
+
+2. **Design table schemas:**
+    - Determine columns for each table
+    - Plan property/API documentation tables
+    - Design configuration option tables
+
+3. **Plan content reduction:**
+    - Identify text to condense
+    - Plan bullet point conversions
+    - Design code example reductions
+
+### 3. Content Transformation
+
+1. **Convert prose to tables:**
+    - Transform property descriptions
+    - Convert API documentation
+    - Tabularize configuration options
+
+2. **Condense text:**
+    - Reduce verbose explanations
+    - Convert paragraphs to bullet points
+    - Remove redundant information
+
+3. **Optimize code examples:**
+    - Keep only essential examples
+    - Remove verbose comments
+    - Use minimal, clear examples
+
+4. **Restructure sections:**
+    - Reorganize for better flow
+    - Merge related sections
+    - Remove unnecessary sections
+
+### 4. Validation
+
+1. **Verify completeness:**
+    - Ensure all essential information retained
+    - Check no critical details lost
+    - Verify all APIs/configs documented
+
+2. **Check accuracy:**
+    - Verify table data is correct
+    - Check code examples work
+    - Confirm no information corrupted
+
+3. **Validate format:**
+    - Check table formatting
+    - Verify markdown syntax
+    - Ensure consistent style
+
+## Formatting Standards
+
+### Tables
+
+- Use consistent column headers
+- Align columns appropriately
+- Use minimal but clear descriptions
+- Include type information where relevant
+
+### Code Examples
+
+- Keep examples minimal and focused
+- Remove unnecessary boilerplate
+- Use clear, descriptive variable names
+- Include only essential comments
+
+### Lists
+
+- Use bullet points for unordered lists
+- Use numbered lists for sequential steps
+- Keep items concise
+- Group related items
+
+### Sections
+
+- Use consistent heading levels
+- Maintain logical hierarchy
+- Use descriptive section names
+- Keep sections focused
+
+## Quality Checklist
+
+After optimization, verify:
+
+- [ ] All essential information retained
+- [ ] No critical details lost
+- [ ] Tables properly formatted
+- [ ] Code examples accurate and minimal
+- [ ] Consistent formatting throughout
+- [ ] Token count significantly reduced
+- [ ] Still readable and understandable
+- [ ] Cross-references maintained
+- [ ] Related documentation links intact
+
+## Common Pitfalls to Avoid
+
+1. **Over-condensation:**
+    - Don't remove essential context
+    - Don't make information unclear
+    - Don't sacrifice clarity for brevity
+
+2. **Inconsistent formatting:**
+    - Maintain consistent table structures
+    - Use consistent terminology
+    - Keep formatting uniform
+
+3. **Lost information:**
+    - Verify all details preserved
+    - Check no APIs/configs missing
+    - Ensure examples still accurate
+
+4. **Poor organization:**
+    - Maintain logical flow
+    - Keep related information together
+    - Don't fragment related content
+
+## Success Metrics
+
+A successfully optimized doc should:
+
+1. **Reduce token count** by 50% or more while retaining all essential
+   information
+2. **Maintain readability** - Still clear and understandable
+3. **Preserve completeness** - All essential details retained
+4. **Improve scannability** - Easier to find specific information
+5. **Maintain accuracy** - No information corrupted or lost
+
+## Examples
+
+### Example 1: API Documentation
+
+**Before (high token count):**
+
+````markdown
+## API Methods
+
+### getData(id: string): Promise<Data>
+
+This method retrieves data for the given ID. It takes a string parameter called
+`id` that represents the unique identifier of the data you want to retrieve. The
+method returns a Promise that resolves to a Data object containing the requested
+data. If the data is not found, the Promise will reject with an error.
+
+Example usage:
+
+```typescript
+const data = await getData('123');
+console.log(data);
+```
+````
+
+````
+
+**After (low token count):**
+```markdown
+## API Reference
+
+| Method | Parameters | Returns | Description |
+| ------ | ---------- | ------- | ----------- |
+| `getData` | `id: string` | `Promise<Data>` | Retrieves data for the given ID |
+
+```typescript
+const data = await getData('123');
+````
+
+````
+
+### Example 2: Configuration Options
+
+**Before (high token count):**
+```markdown
+## Configuration Options
+
+The `outputDir` option specifies the directory where generated files will be written. This should be a valid directory path. The default value is `./output` if not specified.
+
+The `format` option determines the output format of the generated files. It can be set to `json`, `yaml`, or `xml`. The default is `json`.
+
+The `verbose` option enables verbose logging. When set to `true`, the tool will output detailed information about its operations. The default is `false`.
+````
+
+**After (low token count):**
+
+```markdown
+## Configuration
+
+| Property  | Type                      | Default    | Description                          |
+| --------- | ------------------------- | ---------- | ------------------------------------ |
+| outputDir | string                    | `./output` | Output directory for generated files |
+| format    | 'json' \| 'yaml' \| 'xml' | 'json'     | Output format                        |
+| verbose   | boolean                   | false      | Enable verbose logging               |
+```
+
+## Best Practices
+
+1. **Optimize after comprehensive** - Only optimize when doc is complete and
+   comprehensive
+2. **Preserve essential details** - Never remove critical information
+3. **Maintain accuracy** - Verify all information remains correct
+4. **Test examples** - Ensure code examples still work
+5. **Review thoroughly** - Check optimization quality before finalizing
+6. **Iterate if needed** - Re-optimize if token count still too high

package/.cursor/plans/VERSIONING.md

@@ -0,0 +1,207 @@
+# Versioning System
+
+This plan documents the versioning system for docs files and the project as a
+whole.
+
+## Overview
+
+Every file in the `docs/` directory should be versioned using semantic
+versioning (semver). The project as a whole also maintains a version in
+`package.json`.
+
+## Versioning Rules
+
+Versions are compared against the latest commit in the `main` branch. Changes
+are categorized as:
+
+### Patch Version Bump (x.x.X)
+
+Minor changes or corrections:
+
+- Typo fixes
+- Clarifications
+- Formatting fixes
+- Minor corrections to existing content
+- Small additions that don't add new sections
+
+**Example:** Fixing a typo in an API description, correcting a code example,
+clarifying a configuration option.
+
+### Minor Version Bump (x.X.x)
+
+New sections added to a file:
+
+- Adding new API sections
+- Adding new configuration options
+- Adding new patterns or best practices
+- Adding new architectural information
+- Adding new examples or use cases
+
+**Example:** Adding a new "Advanced Patterns" section, documenting a new API
+method, adding new configuration properties.
+
+### Major Version Bump (X.x.x)
+
+Sections replaced or removed from a file:
+
+- Removing entire sections
+- Replacing sections with different content
+- Breaking changes in APIs or configuration
+- Significant restructuring of content
+- Removing deprecated information that changes the doc's scope
+
+**Example:** Removing a deprecated API section, restructuring the entire
+Architecture section, removing support for a major feature.
+
+## Project Versioning
+
+The project as a whole maintains a version in `package.json` (starting at
+`0.0.0`).
+
+### Version Bump Rules
+
+Changes to docs files should increment the project version based on the
+**greatest change** in any docs file:
+
+- If any doc has a **major** version bump → project gets **major** version bump
+- Else if any doc has a **minor** version bump → project gets **minor** version
+  bump
+- Else if any doc has a **patch** version bump → project gets **patch** version
+  bump
+
+**Example:**
+
+- PMD.md: patch bump (1.0.0 → 1.0.1)
+- ESLINT.md: minor bump (1.0.0 → 1.1.0)
+- XPATH31.md: no change
+
+Project version: minor bump (because ESLINT.md had a minor bump, which is
+greater than PMD.md's patch bump)
+
+## Version Tracking
+
+Versions can be tracked in several ways:
+
+### Option 1: File Metadata
+
+Add version information to each doc file:
+
+```markdown
+# PMD Quick Reference
+
+**Version:** 1.0.0 **Last Updated:** 2024-01-15
+
+...
+```
+
+### Option 2: Separate Version File
+
+Maintain a `docs/VERSIONS.json` file:
+
+```json
+{
+	"PMD.md": "1.0.0",
+	"ESLINT.md": "1.1.0",
+	"XPATH31.md": "1.0.0"
+}
+```
+
+### Option 3: Git Tags
+
+Use git tags to track versions:
+
+- Tag format: `docs/PMD/v1.0.0`
+- Compare against tagged versions
+
+## Scripts for Versioning
+
+Scripts can help with versioning by:
+
+1. **Reading markdown files:**
+    - Detect headers/sections
+    - Parse version metadata (if using file metadata approach)
+    - Identify content structure
+
+2. **Comparing with git:**
+    - Compare current state with latest commit in `main` branch
+    - Detect added sections (minor bump)
+    - Detect removed sections (major bump)
+    - Detect changed content (patch bump)
+
+3. **Determining version bumps:**
+    - Analyze change types across all docs
+    - Determine appropriate version bumps
+    - Calculate project version based on greatest change
+
+4. **Updating versions:**
+    - Update version information in docs files
+    - Update `package.json` version
+    - Generate version metadata
+
+5. **Initializing versions:**
+    - Add version information to existing docs
+    - Initialize version tracking for new docs
+    - Set initial versions to `1.0.0`
+
+## Workflow
+
+1. **Make changes** to doc file(s)
+2. **Analyze changes:**
+    - Compare with latest commit in `main` branch
+    - Categorize changes (patch/minor/major)
+    - Determine version bumps needed
+
+3. **Update versions:**
+    - Update doc file version(s)
+    - Update project version in `package.json`
+    - Update version metadata
+
+4. **Commit:**
+    - Commit changes with version information
+    - Include version bumps in commit message
+    - Tag release if appropriate
+
+## Best Practices
+
+1. **Always compare against main** - Use latest commit in `main` branch as
+   baseline
+2. **Categorize accurately** - Be precise about patch vs minor vs major changes
+3. **Document changes** - Note significant changes in commit messages
+4. **Initialize properly** - Set initial versions for all existing docs
+5. **Track consistently** - Use the same versioning approach for all docs
+6. **Update project version** - Always update `package.json` when docs change
+7. **Version on merge** - Determine versions when merging to `main`, not on
+   feature branches
+
+## Examples
+
+### Example 1: Patch Bump
+
+**Change:** Fixed typo in API description
+
+- Before: `getData()` - Retreives data
+- After: `getData()` - Retrieves data
+
+**Version:** 1.0.0 → 1.0.1 (patch)
+
+### Example 2: Minor Bump
+
+**Change:** Added new "Advanced Patterns" section with 5 new patterns
+
+**Version:** 1.0.0 → 1.1.0 (minor)
+
+### Example 3: Major Bump
+
+**Change:** Removed entire "Legacy API" section (deprecated)
+
+**Version:** 1.0.0 → 2.0.0 (major)
+
+### Example 4: Project Version
+
+**Changes:**
+
+- PMD.md: 1.0.0 → 1.0.1 (patch)
+- ESLINT.md: 1.0.0 → 1.1.0 (minor)
+- XPATH31.md: 1.0.0 → 2.0.0 (major)
+
+**Project Version:** 0.0.0 → 1.0.0 (major, because XPATH31.md had a major bump)

package/.cursor/rules/IMPORTANT.mdc

@@ -0,0 +1,97 @@
+# Important Project Guidelines
+
+## Documentation Files
+
+- **Use `docs/*.md` files**: Refer to and use the documentation files in the `docs/` directory for project-specific information and guidelines.
+
+- **Use `.cursor/plans/*.md` files**: Refer to and use planning documents in the `.cursor/plans/` directory for project planning and development guidance.
+
+## Updating Existing Documentation - CRITICAL REQUIREMENT
+
+**MANDATORY:** When updating any file in the `docs/` directory, you **MUST** follow the documented process. This is **NON-NEGOTIABLE**.
+
+**What you MUST do:**
+1. **Understand the workflow first** - Before making any changes to a doc file, understand the complete workflow
+2. **Extract references** - Extract repository URLs, web page URLs, or Salesforce article references from the doc file itself
+3. **Re-research sources** - Extract repository URLs, web page URLs, or other references from the doc file itself. **CRITICAL:** If a repository URL is already present in the existing `docs/*.md` file, extract the repository URL directly from the doc file and proceed to cloning.
+4. **Clone repository** - Clone repo using full permissions to system's temporary folder (if applicable)
+5. **Systematic review** - Go through every URL on the official page and every file in the repo (verify ALL files inspected)
+6. **Verify all content** - All content in markdown file must be verified or removed/changed
+7. **Add missing content** - Anything missing should be added
+8. **Cleanup** - Delete temporary repository directory after inspection
+9. **Verify ALL todos completed** - Before proceeding, verify ALL file inspection todos are completed (count must match file count exactly)
+10. **Optimize** - Actually execute the OPTIMISE.md plan after updates (ONLY after ALL todos completed, read it, apply techniques, don't just mark as done)
+11. **Version** - Follow VERSIONING.md to determine and update version numbers
+
+**What you MUST NOT do:**
+- ❌ Update doc files without understanding the workflow first
+- ❌ Make changes without re-researching sources
+- ❌ Skip repository cloning for repository-based docs
+- ❌ Skip the verification process
+- ❌ Skip file inspection (ALL files must be inspected)
+- ❌ Leave temporary directories on the system
+- ❌ Mark optimization as "done" without actually executing it
+- ❌ Skip optimization or versioning steps
+- ❌ Begin optimization before ALL file inspection todos are completed
+- ❌ Cancel or skip remaining todos because "essential review is complete"
+
+**Reason:** Following the documented workflow ensures accuracy, completeness, and consistency. Skipping steps leads to incomplete or incorrect documentation.
+
+**Enforcement:** If asked to update a doc file, **STOP** and understand the complete workflow before making any changes.
+
+## Repository Cloning and File Inspection
+
+## Repository File Review (Recommended Approach)
+
+- Aim to treat all files in a repository as potentially relevant, not just the obvious ones.
+- When documenting a repository (GitHub, GitLab, etc.), prefer a **systematic, broad review** over focusing only on a few "key files".
+
+- When cloning repositories for documentation work:
+  - Clone to a temporary location outside the main workspace (for example, using `tmpdir()`).
+  - Avoid creating ad-hoc temp folders inside the project workspace.
+
+- For a thorough review of a repository:
+  - Start by generating a complete file listing, excluding standard build and dependency directories:
+    ```bash
+    find . -type f ! -path './.git/*' ! -path './node_modules/*' ! -path './dist/*' ! -path './coverage/*' | sort
+    ```
+  - Use that listing to drive your review and note-taking process.
+  - Prioritize:
+    - All markdown files (`**/*.md`)
+    - Files that define or document the public API
+    - Exported plugins, libraries, or modules that are part of the public surface
+
+- If you use a todo system (for example via `todo_write` and a helper script like `repo-todos`):
+  - Generate todos based on the full file list rather than hand-picking a few files.
+  - Creating todos in small batches (for example, ~20 at a time) can make the process manageable.
+  - Keep todos granular (ideally one per file) so progress and coverage are easy to track.
+
+- As you review files:
+  - Read each file in full and extract the relevant technical and behavioral details.
+  - Update documentation incrementally as you go instead of waiting until the end.
+  - Keep a simple checkpoint for yourself (for example, “number of files reviewed” vs “number of files in listing”) so you can see whether anything has been skipped.
+
+- Before doing higher-level optimization (like running an OPTIMISE-style pass):
+  - Make sure the underlying documentation work is complete enough for that effort to be worthwhile.
+  - Confirm that all files you decided to cover have actually been reviewed and incorporated where relevant.
+
+- After you finish using a cloned repository for documentation:
+  - Clean up any temporary clones/directories so they don’t accumulate over time.
+
+## Versioning
+
+- **MUST follow [VERSIONING.md](.cursor/plans/VERSIONING.md)**: When creating or updating documentation files:
+  - **Creating new docs**: Initialize with version `1.0.0` (or appropriate version) and update project version in `package.json`
+  - **Updating existing docs**: Determine version bump (patch/minor/major) by comparing against latest commit in `main` branch, update doc version, and update project version in `package.json`
+  - See VERSIONING.md for complete rules, examples, and workflow
+  - Version changes are **required** and must be completed before finalizing any doc changes
+
+## Scripts
+
+- **Use scripts via pnpm**: Always run project scripts using `pnpm` as the package manager. For example:
+  - `pnpm build` - Build the project (only when explicitly needed)
+  - `pnpm test` - Run tests
+  - `pnpm lint` - Run linter
+  - `pnpm format` - Format code
+
+- **CRITICAL PERMISSION REQUIREMENT for pnpm commands**: When running `pnpm` commands (including `pnpm install`, `pnpm build`, `pnpm test`, etc.), you **MUST** use `required_permissions: ['network']` or `required_permissions: ['all']` to ensure pnpm commands have network connectivity. pnpm commands require network access to fetch packages from registries. **DO NOT** attempt pnpm commands without network permissions - they will fail with network connectivity errors.

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,13 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Which document or script has the issue?
+
+## What is wrong?
+
+## Anything else?