AgenticDocs 🚀

Agentic & Interactive Markdown Documentation Engine for NestJS and Node.js APIs

AgenticDocs is a dual-purpose documentation engine built directly into your backend service:

1. 👨‍💻 For Developers: A sleek, offline-ready technical documentation portal with dark/light themes, Shadcn-inspired callouts, Mermaid diagram rendering, interactive API proxying, and a symmetrical 4-state collapsible layout.
2. 🤖 For AI Coding Agents (Cursor, Claude Code, Copilot, Antigravity): Automatically generates structured llms.txt, module-level context bundles (llms/:module.md), and raw endpoints for zero-friction agent ingestion.

✨ Key Features

• Dual-Audience Architecture: One documentation source serves both human engineers and machine reasoning agents without any build step or static-site generation overhead.
• 100% Offline & Zero External CDNs: Bundles local parser and Mermaid.js engine directly. Works seamlessly in air-gapped corporate intranets and strict VPCs.
• Symmetrical 3-Column Layout: Left navigation and right table-of-contents outline share an identical in-flow structural column design with 0.2s smooth collapse transitions, zero table overlap, and floating restore tabs.
• AI Agent Context Ingestion:
  • GET /handbook/llms.txt: Canonical index of all technical documentation modules.
  • GET /handbook/llms/:module.md: Deep consolidated context bundle for a specific business domain.
  • GET /handbook/raw/:id: Raw markdown with frontmatter stripped for clean prompt injection.
• Secure Internal API Proxy: Test and verify internal microservice endpoints with configurable target environments (Localhost, UAT, Staging) and automatic auth token propagation.
• Figma Screens with Clickable API Badges: ui-map blocks render a Figma frame (server-side, cached, no images in your repo) with badges that jump to the matching API description.
• Real-Time Version Checker: Background checksum poller notifies developers when documentation has updated on the server without interrupting their reading flow.
• Shadcn UI Standards: Beautiful callouts ([!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]), prev/next pager cards, and ultra-slim custom scrollbars.

📦 Installation

# Using npm
npm install agentic-docs

# Using yarn
yarn add agentic-docs

Peer Dependencies

Ensure you have NestJS installed:

npm install @nestjs/common @nestjs/core reflect-metadata rxjs

🚀 Quick Start

Import AgentDocsModule into your root AppModule:

import { Module } from '@nestjs/common';
import { AgentDocsModule } from 'agentic-docs';
import * as path from 'path';

@Module({
  imports: [
    AgentDocsModule.forRoot({
      core: {
        docsDir: path.resolve(process.cwd(), 'docs'),
        prefix: '/handbook',
        title: 'Core API & Technical Hub',
        defaultModule: 'general',
      },
      runner: {
        enabled: true,
        proxy: true,
        allowedTargets: {
          default: { name: 'Localhost', baseUrl: 'http://localhost:3000' },
          staging: { name: 'Staging Gateway', baseUrl: 'https://staging.example.com/api' },
        },
      },
      llm: {
        enabled: true,
      },
    }),
  ],
})
export class AppModule {}

Start your NestJS server, then open:

• 📖 Reader Portal: http://localhost:3000/handbook
• 🤖 LLM Context Index: http://localhost:3000/handbook/llms.txt

📚 Writing Documents (for humans and AI agents)

• AUTHORING.md is the exact reference: frontmatter, @operation API blocks, links and anchors, ui-map Figma screens, what is not supported (local images). Every example in it is verified by the test suite.

• AI coding agents write better docs when they know these rules. Copy agent-rules/agentic-docs.md into your agent's rules file:

  | Agent | Where | | :--- | :--- | | Claude Code | CLAUDE.md | | Codex and others | AGENTS.md | | Cursor | .cursor/rules/agentic-docs.mdc (add globs: docs/**/*.md) | | GitHub Copilot | .github/copilot-instructions.md |

  After install the files are at node_modules/agentic-docs/AUTHORING.md and node_modules/agentic-docs/agent-rules/agentic-docs.md, so a rule can simply say "read node_modules/agentic-docs/AUTHORING.md before editing docs/".

📁 Recommended Folder Structure & Naming Conventions

AgentDoc is designed with Convention over Configuration. By following a clean folder structure, AgentDoc automatically indexes documents, determines module boundaries, groups navigation trees, and generates domain-specific context for AI Agents without requiring redundant metadata.

1. Folder Hierarchy Pattern (Domain-Driven Documentation)

Organize your markdown files inside docs/ grouped by business domain or microservice feature:

docs/
├── orders/                              # Module: 'orders' (Auto-detected from folder name)
│   ├── order-api.md                     # ID: 'order-api'
│   ├── checkout-flow.md                 # ID: 'checkout-flow'
│   └── fulfillment-spec.md              # ID: 'fulfillment-spec'
├── billing/                             # Module: 'billing'
│   ├── invoicing.md                     # ID: 'invoicing'
│   ├── payment-webhook.md               # ID: 'payment-webhook'
│   └── subscription-lifecycle.md        # ID: 'subscription-lifecycle'
└── overview.md                          # Root file: Module fallback to 'general'

2. Auto-Discovery & Fallback Rules

| Property | Frontmatter Defined | If Frontmatter is Omitted (Auto-Fallback) | | :--- | :--- | :--- | | module | Explicit module: orders | Inherits the folder name (docs/orders/ ➔ orders). Files in root docs/ fallback to defaultModule (general). | | id | Explicit id: custom-doc-id | Inherits the file base name (order-api.md ➔ order-api). | | title | Explicit title: Custom Title | Extracts the first # Heading 1 from the Markdown body. | | order | Explicit order: 1 | Alphabetical ordering by document title. |

3. File Naming Best Practices

• Format: Always use lowercase kebab-case.md (e.g., order-api.md, payment-webhook.md). Avoid spaces, underscores, or accented characters in filenames.
• Semantic Prefixes:
  • api-*: API interface contracts, endpoint tables, status codes (e.g., order-api.md).
  • fsd-* or brd-*: Functional specification documents, business requirements.
  • architecture-* or workflow-*: Flowcharts, sequence diagrams, state machines.
  • user-guide-*: Developer guides, operational walkthroughs.
• Companion Assets: Keep auxiliary files (Postman collections, OpenAPI schemas, diagrams) in dedicated subfolders (e.g., docs/<module>/postman/, docs/<module>/assets/). AgentDoc scans exclusively .md files, ignoring non-markdown binaries.

📝 Document Frontmatter Format

Place your .md files in your configured docsDir. Each file can include standard YAML frontmatter:

---
id: order-checkout-spec
title: Order Checkout & Payment Processing API
module: orders
tags:
  - orders
  - checkout
apiVersion: v1
status: stable
order: 1
---

# Order Checkout & Payment Processing API

Technical documentation for order creation and checkout workflows...

```mermaid
graph LR
    A[Client] -->|Submit Order| B[Gateway]
    B -->|Validate| C[Database]

[!NOTE] All timestamps are in UTC format ISO 8601.

---

## 🌐 Endpoints Overview

| Method | Endpoint | Description |
| :--- | :--- | :--- |
| `GET` | `/handbook` | Interactive technical reader portal UI |
| `GET` | `/handbook/llms.txt` | Standard machine-readable index for AI agents |
| `GET` | `/handbook/llms/:module.md` | Consolidated module context for AI coding agents |
| `GET` | `/handbook/raw/:id` | Pure raw Markdown for single-doc AI prompting |
| `GET` | `/handbook/api/tree` | Structured navigation hierarchy |
| `GET` | `/handbook/api/content/:id` | Document JSON model including parsed operations |
| `GET` | `/handbook/api/version` | Snapshot checksum and document counts |
| `POST` | `/handbook/api/proxy` | Secure proxy runner to execute target endpoints |
| `GET` | `/handbook/api/ui-map/:id/:index` | Resolved hotspots of the Nth `ui-map` block of a document |
| `GET` | `/handbook/figma/image/:id/:index` | PNG of the Nth `ui-map` block, rendered by Figma and cached on the server |

---

## 🖼️ Figma Screens with Clickable API Badges (`ui-map`)

Show a Figma screen in a document and let readers click an API badge on it to jump to that API's
description (in the same document or another one). No screenshots are committed to the repo: the server
renders the frame through the Figma REST API and caches the PNG.

````markdown
```ui-map
figma: https://www.figma.com/design/<fileKey>/<name>?node-id=868-48   # the screen (frame)
title: Cấu hình ca làm việc
hotspots:
  - node: 868:169            # Figma node of the button; box is placed from its bounding box
    method: POST
    path: /shifts
    label: "+ Thêm ca"        # tooltip
    target: fe-api#api-12     # docId#anchor | file.md#anchor | #anchor (same doc)
    placement: top            # optional: top | bottom | left | right
  - pos: [88, 19]             # alternative to node: manual position in % of the image [x, y]
    method: PUT
    path: /shifts/:shiftCode
    target: fe-api#api-13

- **Setup:** set `FIGMA_TOKEN` (personal access token with `file_content:read`) in the environment of the app that
  hosts the handbook, or pass `figma: { token }` to `AgentDocsModule.forRoot`. The token is used only server-side.
  Optional `figma: { cacheDir, cacheTtlMs, scale }`.
- **Figma API quota:** `files/nodes` and `images` are rate-limited per plan. **Starter plans and View/Collab seats get a very small quota** (an exhausted token is blocked for days, `Retry-After` is honoured and shown in the note under the screen). Use a token from a Dev/Full seat on a paid plan, point `cacheDir` at a persistent volume (the default is the OS temp dir, lost on restart) and raise `cacheTtlMs` (default 24 h; the stale copy is still served when Figma refuses). Without a token the block still lists the hotspots (clickable) and says why the image is missing.
- **Getting ids:** *Copy link to selection* on the frame gives the `node-id` for `figma:`; the same for each button gives its `node:`.
- **Anchors:** targets can be headings (auto slug ids) or explicit `<a id="api-12"></a>`; an empty anchor inside a
  table cell highlights its row. `[text](other-doc.md#anchor)` links also navigate between documents.
- **Exposure:** anyone who can open the handbook can see the rendered screens (the image route has no separate auth). Keep the handbook behind your gateway/VPN if the designs are internal.

---

## 🛠️ Configuration Options

```typescript
export interface AgentDocsOptions {
  core: {
    docsDir: string;          // Path to folder containing Markdown files
    prefix?: string;          // Route prefix (default: '/handbook')
    title?: string;           // Portal header brand title
    defaultModule?: string;   // Default module category for unassigned docs
    swaggerPath?: string;     // Relative path or URL to OpenAPI UI (e.g. '/api/docs' or '/docs')
  };
  runner?: {
    enabled?: boolean;        // Enable/disable API testing runner
    proxy?: boolean;          // Allow proxying through backend
    allowedTargets?: Record<string, { name: string; baseUrl: string }>;
  };
  llm?: {
    enabled?: boolean;        // Enable /llms.txt and /llms/:module.md endpoints
  };
  figma?: {
    token?: string;           // default: process.env.FIGMA_TOKEN
    cacheDir?: string;        // default: <os tmpdir>/agent-docs-figma
    cacheTtlMs?: number;      // default: 24h (stale copy served if Figma is unreachable)
    scale?: number;           // PNG export scale, default 2
  };
}
```

---

## 🩺 Troubleshooting

| Symptom | Cause / fix |
| :--- | :--- |
| `Cannot find module 'js-yaml'` at startup | Use `agentic-docs >= 1.1.0` (it declares the dependency), or `npm i js-yaml`. |
| A document shows its file name as title | Add `title:` to the frontmatter or a `# Heading` (title falls back to the first H1 since 1.1.0). |
| `@operation` block does not appear | The block must be closed with `<!-- @end-operation -->` and the id must match `[A-Za-z0-9_.-]+`. |
| `![](./img.png)` shows a broken image | Local images are not served. Use a `ui-map` block (Figma) or an `https://` URL. |
| `ui-map` says "Figma rate limit hit" | Plan quota exhausted (Starter / View seats are tiny). Wait for the time shown, or use a Dev/Full-seat token. Cached screens keep working. |
| `ui-map` says "FIGMA_TOKEN is not set" | Set `FIGMA_TOKEN` (or `figma.token`) on the server that hosts the handbook. |
| `ui-map` shows "node ... not found" | The `node` id is wrong or not inside the `figma:` frame. Copy the link of the element in Figma. |
| Clicking a badge shows "Không tìm thấy mục" | The `target` anchor does not exist in the target document. Add `<a id="..."></a>`. |
| `ui-map: invalid YAML` | Quote values containing `"` or `:` with single quotes. |

---

## 🧪 Testing & Verification

AgentDoc includes 100% unit and integration test coverage:

```bash
npm test
```

---

## 📄 License

MIT © [Khoa Nguyen](LICENSE)