Documentation Navigator Skill

Helps you understand and navigate the multi-site Docusaurus documentation repository.

Quick Reference

Repository Structure

docs/
├── engineering/           # Internal technical docs
│   ├── CLAUDE.md         # Engineering writing rules
│   ├── docs/             # General eng docs
│   │   ├── AI/           # AI workflows, prompts
│   │   ├── Guidelines/   # Dev standards
│   │   ├── Infrastructure and DevOps/
│   │   ├── QA/           # Testing guides
│   │   ├── Query Library/# SQL snippets
│   │   └── Security and Privacy/
│   └── projects/         # Per-project docs
│       ├── Farfalla/     # Main backend
│       ├── Fenice/       # Reader apps
│       ├── Medusa/       # Content intake
│       ├── Volpe/        # Rendering
│       ├── Coniglio/     # Analytics
│       └── Castoro/      # PDF processing
│
├── product/              # Product team docs
│   ├── CLAUDE.md         # Product writing rules
│   └── docs/
│       ├── AI/           # AI features
│       ├── Analytics/    # Reporting
│       ├── Apps/         # Mobile/desktop
│       ├── Commerce/     # Payments, subs
│       ├── Content/      # Product mgmt
│       ├── Dashboard/    # Admin panels
│       ├── Reader/       # Reading UX
│       ├── Storefront/   # Store features
│       ├── Team/         # Internal processes
│       ├── Tenants/      # Customer-specific
│       └── Users/        # User management
│
├── public/               # External API docs
│   ├── CLAUDE.md         # API writing rules
│   └── docs/
│       ├── Rest_API/     # Endpoints
│       ├── Integrations/ # 3rd party
│       ├── Notifications/# Webhooks
│       └── Guides/       # Tutorials
│
└── support/              # Help articles

Which Site to Use?

Content Type	Site	Path
API internals, architecture	Engineering	engineering/docs/
Project-specific tech docs	Engineering	engineering/projects/{Project}/
Database queries	Engineering	engineering/docs/Query Library/
Feature specs, user flows	Product	product/docs/
Customer use cases	Product	product/docs/Tenants/
Public API endpoints	Public	public/docs/Rest_API/
Integration guides	Public	public/docs/Integrations/
Customer help	Support	support/docs/

Finding Content

# Search by keyword across all docs
grep -r "keyword" engineering/ product/ public/ --include="*.md"

# Find files by name pattern
find . -name "*subscription*" -type f

# List docs in a domain
ls -la product/docs/Commerce/

Creating New Documentation

1. Identify the audience → Pick the right site
2. Read the site's CLAUDE.md → Follow writing rules
3. Check domain organization → Place in correct folder
4. Use frontmatter template:

---
id: filename_in_snake_case
slug: filename_in_snake_case
title: Document Title
sidebar_label: Docs Navigator
sidebar_position: 1
author: Team Name
tags: [category, subcategory, type]
---

5. Add minimum 3 tags from site's docs/tags.yml
6. Use correct link format: [text](./folder/file.md)

Business Domains

Content is organized by domain across engineering/product:

Domain	Engineering Focus	Product Focus
AI	ML pipelines, prompts	AI features for users
Analytics	Data pipelines, Coniglio	Reports, dashboards
Commerce	Payment APIs, Stripe	Subscriptions, coupons
Content	Medusa, ONIX, intake	Product management
Identity	Auth systems, tokens	User permissions
Reader	Volpe, Fenice internals	Reading experience
Storefront	Frontend architecture	Store customization

Common Tasks

"Where do I document a new API endpoint?"

• Internal endpoint → engineering/projects/{Project}/ or engineering/docs/
• Public endpoint → public/docs/Rest_API/{resource}/

"Where do I document a new feature?"

• Technical implementation → engineering/docs/ or engineering/projects/
• User-facing behavior → product/docs/{Domain}/
• Customer-facing guide → public/docs/Guides/ or support/docs/

"Where's the docs for project X?"

Check engineering/projects/{ProjectName}/:

• Farfalla, Fenice, Medusa, Volpe, Coniglio, Castoro

"How do I run the docs locally?"

npm run start:engineering   # Engineering site
npm run start:product       # Product site
npm run start:public        # Public site

Validation

Before committing:

npm run validate  # Check frontmatter and tags
npm run fix       # Auto-fix common issues

Platform Context

Publica.la = SaaS B2B2C digital publishing platform

Key concepts:

• Tenant = Customer (publisher/bookstore)
• Store = Tenant's e-commerce site
• Product = Digital content sold (ebook, audiobook, magazine)
• End User = Person who buys/reads content

Key services:

• Farfalla = Main backend (Laravel)
• Medusa = Content intake (ONIX, automations)
• Volpe = Single-page reader
• Fenice = Mobile/desktop apps
• Coniglio = Analytics
• Castoro = PDF processing