CLAUDE

FieldPulse Docs — Agent Instructions

Project Structure

This is a Mintlify documentation site with two content types:

1. Help Center (source_type: "help-center") — User-facing product documentation migrated from Intercom. Found throughout all tabs.
2. Engineering (source_type: "engineering") — Current-state Laravel/Angular technical documentation from fp-documentation. Lives in engineering/ subdirectories within each module and dedicated groups under Architecture.

Directory Conventions

core-platform/customers/               # Help center articles
core-platform/customers/engineering/    # Engineering docs (Laravel model, API, routes)
architecture/current-state/             # Architecture blueprint (from AGENT.md)
architecture/data-model/                # Cross-cutting database references
architecture/design-system/             # Legacy design system docs
architecture/navigation-map/            # Frontend route documentation

Rule: Every file under an engineering/ directory must have source_type: "engineering" in frontmatter.

Frontmatter

Engineering pages (required fields)

---
title: "API Endpoints: Customer Model (Laravel)"
description: "23 REST endpoints for the Customer Eloquent model"
source_type: "engineering"
source_path: "docs/database/models/customer/API_ENDPOINTS.md"
confidence: "HIGH"
---

Confidence levels

• HIGH — Verified against source code. Default assumption; omit the confidence badge for HIGH pages.
• MEDIUM — Inferred from patterns or partially verified.
• LOW — Placeholder or speculative.

Agent Search Strategies

When rebuilding a module, always fetch both content types:

1. Search for the module name to get help center articles (user-facing behavior)
2. Search for “API Endpoints: ” or “Technical Reference: ” to get engineering docs (implementation details)
3. Search for cross-cutting references in architecture/data-model/ for database constraints, relationships, and enum values

Title convention (engineering pages)

Titles front-load the content type for better MCP disambiguation:

• "API Endpoints: Customer Model (Laravel)"
• "Technical Reference: Pricebook Model (Laravel)"
• "Model Reference: Customer (Eloquent)"

Help center titles use natural language: "Creating a Customer", "Customer Portal".

MDX Content Rules

• Curly braces must be escaped in prose: All {variable} patterns in MDX content must be written as \{variable\}. Bare curly braces are interpreted as JSX expressions by the MDX compiler, causing build failures that can break the entire site. The convert-engineering-docs.ts script handles this automatically; manual edits must escape too.
• No <Tabs> wrapping full page content: Wrapping an entire page in <Tabs> breaks Mintlify’s TOC parser and page scrolling. Use separate standalone pages instead (e.g., api-endpoints.mdx, data-contracts.mdx, laravel-routes.mdx).
• Pipe characters in table inline code: | inside backtick code within table rows must be escaped as \| to prevent the table parser from splitting cells incorrectly.
• .mintignore: Non-documentation directories (.fp-documentation-source/, docs/plans/, todos/, scripts/) are excluded from Mintlify processing via .mintignore.

Engineering Content Lifecycle

Engineering docs capture the current Laravel/Angular system. As modules are rebuilt in React/Node:

1. Mark the engineering page confidence: "DEPRECATED"
2. Keep it visible until the new module is fully shipped
3. Remove via: find . -type d -name "engineering" -exec rm -rf {} + plus Architecture expansion dirs

Hidden Navigation Content

All 38 Engineering sub-groups and the Architecture tab are hidden from public navigation via "hidden": true in docs.json. Pages remain accessible via direct URL and indexed for AI/MCP/search (seo.indexing: "all").

Rules:

• Never set "hidden": false to unhide — this causes undefined behavior in Mintlify. Delete the "hidden" property entirely.
• After running generate-nav.ts, always re-run npx tsx scripts/hide-engineering-nav.ts to restore hidden properties. The nav generator has no awareness of hidden and will strip it.
• Script: scripts/hide-engineering-nav.ts adds hidden: true to all groups with group === "Engineering" and icon === "code", plus the Architecture tab.

Scripts

Script	Purpose
scripts/convert-engineering-docs.ts	Convert fp-documentation .md → Mintlify .mdx
scripts/generate-nav.ts	Auto-generate docs.json navigation from filesystem (⚠️ run hide-engineering-nav.ts after)
scripts/hide-engineering-nav.ts	Re-apply hidden: true to Engineering groups + Architecture tab
scripts/check-guards.ts	CI guard checks (Tailwind, SVG, OG image, engineering frontmatter, bare JSX)
scripts/validate-nav.ts	Validate docs.json references exist on disk
scripts/rewrite-help-links.ts	Rewrite help.fieldpulse.com links to internal paths
scripts/refresh-api-docs.ts	Orchestrate API docs refresh: diff, create stubs, update nav
scripts/convert-postman-to-openapi.ts	Convert Postman collection → OpenAPI 3.0 spec
scripts/sync-from-intercom.ts	Sync help center articles from Intercom API
scripts/audit-intercom-parity.ts	Audit parity between Intercom and local articles
scripts/generate-redirect-map.ts	Generate Intercom→Mintlify URL redirect map (CSV + JSON)

Skills

Skill	Purpose
/api-refresh [path]	Refresh API reference from a Postman collection (dry-run → confirm → apply → validate)
/find-mentions <term>	Search all help center articles for mentions of a term
/redirects	Generate Intercom→Mintlify redirect map (dry-run → confirm → write CSV + JSON)
/publish	Stage, commit, push, and create a PR for documentation changes
/update-article <path>	Open and edit a help center article with MDX validation

Key Files

• docs.json — Mintlify site configuration and navigation
• scripts/module-config.json — Help center module mapping (4000+ lines)
• scripts/engineering-module-mapping.json — Engineering doc source → target mapping

Help Center Redesign (Active)

Spec-driven implementation of two design mockups onto this Mintlify project.

• Spec: specs/help-center-redesign/SPEC.md — source of truth for all design tokens, components, and feasibility decisions
• Mockups: design/fieldpulse-help-center (1).html (hub page), design/fieldpulse-release-notes (12).html (changelog)
• Linear epic: ET-392 with 19 child issues (ET-393 through ET-411)
• CSS class conventions: hc-* prefix for help center landing components, cl-* prefix for changelog components
• Custom-mode pages: index.mdx (landing) and changelog/index.mdx use mode: "custom" — no native sidebar/TOC/footer
• QA evidence: saved to .qa/[issue-id]/ per issue
• Design tokens: unified set in :root — --navy, --cobalt, --sky, --fog, --aqua, --quartz, --paper, --rule, --rule-strong, --muted
• Font: Montserrat (Google Fonts) — heading weight 700, body weight 500