# Ordio Documentation

Complete documentation for the Ordio project, including development guides, technical references, and AI agent configuration.

**Last Updated:** 2026-04-01

## 📋 Documentation framework

This tree is optimized for humans and Cursor agents. **Day-to-day navigation** stays in a small set of entry files; one-off audits and 2026-01 framework sprint reports live under [archive/2026-04-01-docs-cleanup/stale-docs-root/](archive/2026-04-01-docs-cleanup/stale-docs-root/) (see its README).

### Quick navigation

- **[Documentation hygiene log](DOCUMENTATION_HYGIENE_LOG.md)** — Maintenance SSOT + changelog
- **[Scale & scope](DOCUMENTATION_SCALE_AND_SCOPE.md)** — Why the repo has so many files (blog pipeline vs meta-docs)
- **[Master index](DOCUMENTATION_MASTER_INDEX.md)** — Browse by category
- **[Documentation inventory](DOCUMENTATION_INVENTORY.md)** — File list (regenerate: `make docs-inventory`)
- **[Redundancy report](DOCUMENTATION_REDUNDANCY_REPORT.md)** — Consolidation hints (regenerate: `make docs-redundancy`)
- **[Documentation gaps (pointer)](DOCUMENTATION_GAPS.md)** — Where to look for “what’s missing”; full analyses archived
- **[Next steps](DOCUMENTATION_NEXT_STEPS.md)** — Ongoing content themes
- **[Standards](DOCUMENTATION_STANDARDS.md)** — Naming, structure, dates
- **[Maintenance process](DOCUMENTATION_MAINTENANCE_PROCESS.md)** — Workflows
- **[AI agent guide](AI_AGENT_GUIDE.md)** — Discovery patterns
- **[Link validation report](LINK_VALIDATION_REPORT.md)** — `python3 scripts/documentation/validate-links.py`
- **[Rule validation report](RULE_VALIDATION_REPORT.md)** — `python3 scripts/documentation/validate-rules.py`
- **[Generation scripts](DOCUMENTATION_GENERATION_SCRIPTS.md)** — Scaffold / batch generators still in repo

## Quick Start

New to Ordio documentation? Start here:

1. **[Quick Start Guide](QUICK_START.md)** - Common tasks and quick links
2. **[AI Agent Documentation](ai/)** - For AI agents working with the codebase
3. **[Guides](guides/)** - User-facing guides for creating pages and features

## Documentation Structure

### 📚 [Guides](guides/)

User-facing guides for creating and maintaining Ordio pages.

- **[Comparison Pages Guide](guides/comparison-pages/COMPARISON_PAGES_GUIDE.md)** - Step-by-step instructions for creating competitor comparison pages
- **[Page Type Guides](guides/PAGE_TYPE_GUIDES.md)** - Quick reference for all page types
- **[Tools Pages](guides/tools-pages/)** - Calculator and tool page guides

### 📦 [Content Documentation](content/)

Content-specific documentation for tools, pages, competitors, and product features.

- **[Tools Pages](guides/tools-pages/)** - Documentation for all 19 tools/calculators (consolidated)
  - **[Tools Inventory](guides/tools-pages/TOOLS_INVENTORY.md)** - Complete tool list
  - **[Testing Files](guides/tools-pages/testing/)** - Testing and validation files
  - **[Quality Report](content/tools/TOOLS_DOCUMENTATION_QUALITY_REPORT.md)** - Documentation quality assessment (legacy)
- **[Pages](content/pages/)** - Documentation for all page types (comparison, product, industry, etc.)
  - **[Comparison Pages](content/pages/comparison-pages/)** - SEO comparison pages (distinct from competitors)
  - **[SEO-Only Pages](content/pages/comparison-pages/SEO_ONLY_COMPARISON_PAGES.md)** - Pages created for SEO traffic
- **[Competitors](content/competitors/)** - Direct competitor profiles (distinct from comparison pages)
  - **[Competitors Inventory](content/competitors/COMPETITORS_INVENTORY.md)** - Complete competitor list
  - **[Direct Competitors](content/competitors/DIRECT_COMPETITORS_LIST.md)** - Confirmed direct competitors
  - **[Competitors vs Comparison Pages](content/competitors/COMPETITORS_VS_COMPARISON_PAGES.md)** - Critical distinction guide
- **[Product Features](content/product-features/)** - Ordio feature documentation
- **[Blog](content/blog/)** - Blog inventory (for future WordPress migration)

### 🔧 [Systems](systems/)

Complete documentation for major Ordio systems.

- **[Systems Documentation](systems/README.md)** - Master index for all systems documentation
- **[Forms & Components](systems/)** - Forms, shared components, and HubSpot API integration
  - **[Form-to-Page Mapping](systems/forms/FORM_TO_PAGE_MAPPING.md)** - Complete mapping of all form endpoints
  - **[Form Configuration Reference](systems/forms/FORM_CONFIGURATION_REFERENCE.md)** - Form GUIDs and field mappings
  - **[Shared Components](systems/shared-components/)** - Email modal, UTM tracking, GTM tracking, lead capture
  - **[HubSpot API Reference](systems/apis/HUBSPOT_API_REFERENCE.md)** - Complete API endpoint documentation
  - **[Developer Quick Reference](systems/DEVELOPER_QUICK_REFERENCE.md)** - Quick reference guide
- **[ShiftOps](systems/shiftops/)** - ShiftOps tool documentation (API, architecture, development)
- **[Lead Capture](systems/lead-capture/)** - Lead capture popup system
- **[Product Updates](systems/product-updates/)** - Product Updates CMS

### 📖 [Reference](reference/)

Technical reference documentation.

- **[API Reference](reference/api/)** - API endpoints, error handling, cron jobs
- **[Architecture](reference/architecture/)** - System architecture and site structure
- **[Schemas](reference/schemas/)** - Schema documentation (to be added)

### 💻 [Development](development/)

Developer-focused documentation.

- **[Setup](development/setup/)** - Environment setup and configuration
- **[Testing](development/testing/)** - Testing guides and protocols
- **[Troubleshooting](development/troubleshooting/)** - Common issues and solutions
- **[JavaScript Logging Best Practices](development/JAVASCRIPT_LOGGING_BEST_PRACTICES.md)** - Console logging guidelines

### 🤖 [AI Agent Documentation](ai/)

Documentation specifically designed for AI agents.

- **[Cursor Playbook](ai/cursor-playbook.md)** - Complete workflow guide for Cursor AI
- **[Rule Hierarchy](ai/rule-hierarchy.md)** - Cursor rule architecture and decision tree
- **[Validation Workflows](ai/validation-workflows.md)** - Validation procedures
- **[Cursor Model Configuration](ai/CURSOR_MODEL_CONFIGURATION.md)** - Configure Cursor for best results

## Cursor Rules vs Documentation

**`.cursor/rules/*.mdc` files:**

- Purpose: AI agent instructions that trigger automatically based on file patterns
- Audience: Cursor AI agent
- Location: `.cursor/rules/` directory

**`.md` documentation files (this folder):**

- Purpose: Human-readable reference guides, tutorials, and technical documentation
- Audience: Developers and team members
- Location: `docs/` directory

The Cursor rules provide concise, actionable instructions for the AI agent, while this documentation provides comprehensive context and detailed explanations for human developers.

## Quick Links

- **Creating a new comparison page?** → [Comparison Pages Guide](guides/comparison-pages/COMPARISON_PAGES_GUIDE.md)
- **Working on ShiftOps?** → [ShiftOps Documentation](systems/shiftops/)
- **Need to understand Cursor rules?** → [Rule Hierarchy](ai/rule-hierarchy.md)
- **Setting up integrations?** → [Setup Documentation](development/setup/)
- **Looking for validation workflows?** → [Validation Workflows](ai/validation-workflows.md)
- **Date management standards?** → [Date Management Guidelines](DATE_MANAGEMENT_GUIDELINES.md)
- **Project ownership & contact?** → See `.cursor/rules/global.mdc` for project ownership details

## Contributing

When adding new documentation:

1. Place guides in `guides/`
2. Place system docs in `systems/`
3. Place reference docs in `reference/`
4. Place development docs in `development/`
5. Place AI agent docs in `ai/`
6. Update the relevant README.md index
7. Cross-reference related documents
8. **Always add "Last Updated: YYYY-MM-DD" date**

**Note:** The `docs/` directory and `.cursor/rules/` are now tracked in Git for team collaboration. Only temporary files (`docs/drafts/`, `docs/temp/`) are excluded.

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.  
See [DATE_MANAGEMENT_GUIDELINES.md](DATE_MANAGEMENT_GUIDELINES.md) for date standards.

## Support

For questions about:

- **Page creation workflows** → See [Cursor Playbook](ai/cursor-playbook.md)
- **Specific page types** → See [Page Type Guides](guides/PAGE_TYPE_GUIDES.md)
- **ShiftOps development** → See [ShiftOps Documentation](systems/shiftops/README.md)
- **Technical setup** → See [Setup Documentation](development/setup/)
- **Date management** → See [Date Management Guidelines](DATE_MANAGEMENT_GUIDELINES.md)

## Documentation Health

**Status:** ✅ **Framework Established and Operational**

- **1,143+ documentation files** - Comprehensive coverage
- **44 Cursor rules** - Complete rule set (all standardized)
- **Documentation tracked in Git** - Team collaboration enabled
- **Structured organization** - Clear hierarchy and navigation
- **Maintenance processes** - Automated checks and update workflows
- **AI-optimized** - Discovery patterns and semantic search
- **Validation automated** - 7 validation scripts operational
- **Templates ready** - 5 templates for all content types

**Framework status:**

- [Documentation hygiene log](DOCUMENTATION_HYGIENE_LOG.md) — maintenance SSOT; legacy audit/handoff narratives under `docs/archive/2026-04-01-docs-cleanup/docs-root-meta-audits/`
- [Documentation next steps](DOCUMENTATION_NEXT_STEPS.md) — ongoing themes
- [Stale root reports archive](archive/2026-04-01-docs-cleanup/stale-docs-root/) — superseded audits, gap exports, validation snapshots (2026-04-01)

See [DOCUMENTATION_INVENTORY.md](DOCUMENTATION_INVENTORY.md) for the generated file list.

## For Cursor AI Agents

### Finding Documentation

When searching for documentation:

1. **Content-specific docs:** Check `docs/content/` first

   - Tools → `docs/content/tools/`
   - Pages → `docs/content/pages/`
   - Competitors → `docs/content/competitors/`
   - Product Features → `docs/content/product-features/`

2. **System docs:** Check `docs/systems/`

   - Forms & Components → `docs/systems/` (forms, shared components, APIs)
   - ShiftOps → `docs/systems/shiftops/`
   - Lead Capture → `docs/systems/lead-capture/`
   - Product Updates → `docs/systems/product-updates/`

3. **Guides:** Check `docs/guides/`

   - Page creation guides
   - Tool documentation guides
   - Comparison page guides

4. **Cursor Rules:** Check `.cursor/rules/`
   - See [.cursor/rules/README.md](.cursor/rules/README.md) for rule index

### Documentation Patterns

- **Tool docs:** `docs/content/tools/[tool-slug]-documentation.md`
- **Competitor docs:** `docs/content/competitors/[competitor-slug]-profile.md`
- **Page docs:** `docs/content/pages/[page-type]/[page-slug]-documentation.md`
- **Feature docs:** `docs/content/product-features/[feature-slug]-documentation.md`

### Before Creating New Documentation

1. **Search existing docs** using patterns above
2. **Check [DOCUMENTATION_INVENTORY.md](DOCUMENTATION_INVENTORY.md)** for existing files
3. **Review [DOCUMENTATION_GAPS.md](DOCUMENTATION_GAPS.md)** to see what's missing
4. **Follow [DOCUMENTATION_STANDARDS.md](DOCUMENTATION_STANDARDS.md)** for structure
5. **Update relevant inventory files** after creating new docs

See [AI_AGENT_GUIDE.md](AI_AGENT_GUIDE.md) for complete Cursor AI documentation discovery guide.

## AI Optimization & Cross-Reference Navigation

### Semantic Search

- **[Semantic Search Index](ai/SEMANTIC_SEARCH_INDEX.md)** - Common queries mapped to documentation
- **[Rule Discovery Patterns](ai/RULE_DISCOVERY_PATTERNS.md)** - File paths mapped to applicable rules

### Cross-Reference Navigation

- **[Rule to Documentation Mapping](ai/RULE_TO_DOC_MAPPING.md)** - Bidirectional mapping between rules and docs
- **[Rule Dependency Graph](ai/RULE_DEPENDENCY_GRAPH.md)** - Visual rule relationships and dependencies

### Quality & validation

- **[Documentation quality checklist](DOCUMENTATION_QUALITY_CHECKLIST.md)** — Quality standards for AI agents
- **[Rule validation report](RULE_VALIDATION_REPORT.md)** — Rule metadata (regenerate via `scripts/documentation/validate-rules.py`)
- Historical completeness / cross-reference snapshots — [stale-docs-root archive](archive/2026-04-01-docs-cleanup/stale-docs-root/)