> ## Documentation Index > Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt > Use this file to discover all available pages before exploring further. # STANDARD # Pcnaid Documentation Network — Architecture Standard **Version:** 1.1 **Status:** Approved **Approved by:** Abdul Badran, CEO, Pcnaid Inc. **Approval date:** 2026-05-20 **Primary repository:** `github.com/PcnaidInc/documentation` **Mirror (read-only):** `bitbucket.org/atlasrealty/documentation` **Custom domain:** `https://docs.pcnaid.com` **Docs platform:** Mintlify (renders from the GitHub repo) *** ## How to Read This Document This file is the single authoritative reference for every AI model, LLM agent, workflow, automation, and human contributor that touches the Pcnaid documentation repository. It is written to eliminate ambiguity. If this document does not cover a scenario, the correct action is to stop and ask a human — never invent a convention. **Rules for AI/LLM models reading this file:** 1. Do not deviate from naming conventions, folder structures, or frontmatter schemas defined here — even if you believe a deviation would be "better." 2. Do not create folders or files that are not explicitly allowed by the hierarchy defined in §3. 3. When in doubt between two valid interpretations, choose the one that results in fewer folders and fewer files. 4. Never delete or overwrite a file with `review_status: locked` in its frontmatter. 5. Never auto-merge a PR. All PRs require human approval or Reviewer Bot approval (§12). 6. Always read this entire file before beginning any work on the repository. Do not skim. *** ## 1. Core Vocabulary (Locked Terms) These terms have precise meanings throughout the network. Do not use them loosely or interchangeably. * **Network** — the entire `PcnaidInc/documentation` repository. There is exactly one Network. It has one namespace, one search index, one brand identity, and one custom domain (`docs.pcnaid.com`). * **Hub** — an industry or ecosystem landing page that groups multiple related Nodes. A Hub does not contain content of its own beyond a short introduction. Its pages are 90% auto-generated from the Nodes that reference it. Example: "Shopify Ecosystem Hub" groups every Pcnaid Shopify app, extension, and theme. * **Node** — a single product's complete documentation set. A Node is the atomic unit of the network. Every product gets exactly one Node, and that Node contains everything about that product: merchant docs, developer docs, partner docs, help center, KB, glossary, changelog, and API reference. Example: "Pcnaid Loyalty & Rewards" is a Node. * **Track** — an audience lens inside a Node. There are exactly three Tracks. No more may be added without a governance review (§15): * `merchant` — non-technical end-users. No code blocks longer than 3 lines. Heavy screenshots. Plain language. * `developer` — technical integrators, contributors, API consumers. Code-first. Assumes Git and terminal literacy. * `partner` — business affiliates, resellers, co-marketing partners. Prose plus tables. Contracts, commissions, revenue examples. No code. Includes downloadable PDF versions of legal documents. * **Surface** — a functional area inside a Track. Surfaces are the leaf-level containers. The allowed Surfaces per Track are defined in §5 and are a closed set. * **Leaf** — an individual `.mdx` content file. The smallest addressable unit in the network. * **Edge** — a cross-link between Nodes, Hubs, or Leaves, declared in frontmatter. Edges are machine-readable and used by automation to build the link graph, related-content sidebars, and broken-link reports. * **scope.json** — a machine-readable configuration file at the Hub and Node level that governs: which folders the scoped live chat retrieves from, which LLM model is used for that scope, which llms.txt files are generated, and which parent scope to fall back to. *** ## 2. Infrastructure Stack (Simplified) The entire documentation network runs on three infrastructure components. No external databases, no third-party vector stores, no paid hosting beyond what is already in use. ### 2a. GitHub Actions (All Automation) Every automation task — nightly rebuilds, llms.txt generation, Confluence-to-Markdown sync, link checking, freshness monitoring, doc update PRs from code changes — runs as a GitHub Actions workflow inside the `PcnaidInc/documentation` repository. **AI/LLM access for workflows:** * **GitHub Copilot** — available natively in GitHub Actions. * **OpenAI Codex** — authenticated via OAuth (GitHub's built-in OpenAI integration). Do NOT use API keys. Do NOT burn startup credits for documentation tasks. * **Anthropic Claude** — authenticated via OAuth (GitHub's built-in Anthropic integration). Do NOT use API keys. Do NOT burn startup credits for documentation tasks. **Why this matters:** All three LLMs are available to GitHub Actions workflows at zero marginal cost via OAuth integrations. The $2,500 OpenAI credits, $500 Anthropic credits, and all other startup credits listed in §2d are reserved exclusively for Pcnaid's actual products (Shopify apps, custom web apps, mobile apps, etc.) — never for documentation maintenance. ### 2b. SQLite (All Data Storage) Every data storage need in the documentation network is served by SQLite database files committed to the repository (for small, slow-changing data) or stored as GitHub Actions artifacts (for larger, frequently-rebuilt data like vector indexes). **Use cases:** * **Scope indexes** for scoped live chat — one `.sqlite` file per Node/Hub containing the vectorized chunks for that scope. * **Link graph** — a single `graph.sqlite` at the network root containing all edges between all Leaves, Nodes, and Hubs. * **Metadata lookups** — contributor data, sync timestamps, review history, credit burn logs. * **Search index supplements** — any structured data that Mintlify's built-in search doesn't cover. **Rules:** * SQLite files larger than 50 MB must be stored as GitHub Actions artifacts, not committed to the repo. * SQLite files smaller than 50 MB may be committed to the repo under the `/data/` top-level folder. * Every SQLite file must have a corresponding schema migration file under `/data/migrations/`. * Never use MySQL, PostgreSQL, MongoDB, Redis, Supabase, or any external database for documentation infrastructure. ### 2c. GitHub Pages + Mintlify (Rendering) The documentation site at `docs.pcnaid.com` is rendered by Mintlify from the GitHub repo. Mintlify handles: * Static site generation from `.mdx` files. * Built-in search indexing. * Built-in AI chat widget (scoped by page context). * OpenAPI spec rendering for API reference pages. * Custom domain SSL. **GitHub Pages** serves as a fallback for any static assets, runbooks, or tools that Mintlify doesn't render (e.g., the playground proxy, status embeds). ### 2d. Startup Credits (Reserved for Products, NOT Documentation) The following credits are available to Pcnaid but are explicitly NOT to be used for documentation infrastructure. They are reserved for actual product development: | Provider | Credits | Reserved For | | ------------------ | --------------------- | ------------------------------------------ | | OpenAI | \$2,500 | Shopify apps, custom web apps, mobile apps | | Anthropic | \$500 | Shopify apps, custom web apps, mobile apps | | Cloudflare | (free tier + credits) | Product hosting, CDN for apps | | Chroma (TryChroma) | credits | Product-level RAG if needed | | Render | credits | Product app hosting | | Sentry | credits | Product error tracking | | PostHog | credits | Product analytics | | Datadog | credits | Product monitoring (if needed) | | MongoDB | credits | Product databases | | Redis | credits | Product caching | | Auth0 | credits | Product authentication | | Clerk | credits | Product authentication | | ElevenLabs | credits | Product voice features (future) | | Make.com | credits | Product-level automation triggers | | Modal | credits | Product compute | | Linear | credits | Product issue tracking | | Amplitude | credits | Product analytics | | Mixpanel | credits | Product analytics | | Algolia | credits | Product search | | Airtable | credits | Product data management | | Daytona | credits | Product dev environments | | Confluent Cloud | credits | Product event streaming (if needed) | | GitLab | credits | Product CI/CD (if needed) | | TiDB | credits | Product databases (if needed) | | Bubble.io | credits | Product rapid prototyping (if needed) | | Asana | credits | Product project management | | Cobo.com | credits | Product fintech (if needed) | **Enforcement rule:** If an AI model or automation attempts to configure an API key or OAuth connection to any of the above services for documentation purposes, it must stop and flag the action for human review. Documentation runs on GitHub Actions + SQLite + Mintlify only. *** ## 3. Folder Layout (Complete Reference) The repository follows a strict hierarchy. This section shows the full depth of the tree with concrete examples so that no AI model needs to guess how deep folders go or what they contain. ### 3a. Top-Level Structure ``` / ├── architecture/ │ └── STANDARD.md ← THIS FILE (never auto-edited) ├── namespace/ │ ├── index.mdx ← global landing page for docs.pcnaid.com │ ├── llms.txt ← auto-generated, slim index of all Hubs/Nodes │ ├── llms-full.txt ← auto-generated, full Markdown export for IDE/agent ingestion │ └── scope.json ← namespace-level chat scope (indexes entire network) ├── hubs/ │ ├── shopify-ecosystem/ ← example Hub │ │ ├── index.mdx ← Hub landing (90% auto-generated from linked Nodes) │ │ ├── llms.txt ← auto-generated, catalog of this Hub's Nodes │ │ └── scope.json ← Hub-level chat scope │ ├── small-business-stack/ ← another example Hub │ │ ├── index.mdx │ │ ├── llms.txt │ │ └── scope.json │ └── merchant-omnichannel/ ← another example Hub │ ├── index.mdx │ ├── llms.txt │ └── scope.json ├── nodes/ │ └── (see §3c for full Node structure) ├── shared/ │ ├── brand/ ← logos, color tokens, typography │ ├── snippets/ ← MDX fragments reused across Tracks │ ├── assets/ ← images, SVGs, videos │ ├── legal/ ← terms, privacy policy, partner agreements │ └── templates/ ← MDX page templates for AI to clone ├── data/ │ ├── graph.sqlite ← network-wide link graph (auto-rebuilt nightly) │ ├── analytics.sqlite ← page views, search queries, feedback │ └── migrations/ ← schema migration files for all SQLite DBs ├── automation/ │ ├── prompts/ ← system prompts for each automation bot │ │ ├── sync-bot.md │ │ ├── reviewer-bot.md │ │ └── hub-rebuilder.md │ ├── templates/ ← Jinja/Mustache templates for auto-generated pages │ └── scripts/ ← Python/Node utility scripts called by workflows ├── .github/ │ ├── workflows/ ← GitHub Actions workflow files (one per automation) │ │ ├── nightly-sync.yml │ │ ├── reviewer-bot.yml │ │ ├── hub-rebuilder.yml │ │ ├── link-checker.yml │ │ ├── freshness-monitor.yml │ │ ├── llms-txt-generator.yml │ │ └── confluence-sync.yml │ ├── CODEOWNERS ← routes PR reviews by folder │ └── pull_request_template.md ├── mintlify.json ← Mintlify workspace configuration └── README.md ← repo overview, links to this STANDARD ``` ### 3b. Top-Level Categories (Closed Set) Products are organized into exactly these categories under the `nodes/` folder. This list is closed. Adding a new category requires a governance review (§15). ``` nodes/ ├── services/ ← consulting, bookkeeping, strategy, entity formation, │ merchant processing, utilities, telecom, etc. ├── shopify/ ← every Shopify app, theme, extension, POS integration ├── web-apps/ ← custom SaaS web applications ├── mobile-apps/ ← iOS, Android, cross-platform ├── browser-extensions/ ← Chrome, Firefox, Edge, Safari ├── desktop-apps/ ← Electron, native Windows/macOS/Linux ├── integrations/ ← middleware, connectors, API gateways between products └── hardware/ ← physical products, POS terminals, ATMs (if applicable) ``` ### 3c. Full Node Structure (6-Level Example) Below is the complete folder tree for a single Node, expanded to show all six levels. Every Node follows this exact skeleton. When an AI creates a new Node, it clones this structure and populates the manifest files. **Example: Shopify Loyalty & Rewards app** ``` nodes/shopify/loyalty-rewards/ ← LEVEL 1: Category + Node ├── node.json ← machine-readable Node manifest ├── index.mdx ← Node landing page ├── scope.json ← Node-level chat scope config ├── llms.txt ← auto-generated, slim product index ├── llms-full.txt ← auto-generated, full product export │ ├── merchant/ ← LEVEL 2: Track │ ├── _track.json ← Track manifest (display name, icon, description) │ ├── index.mdx ← Track landing ("Welcome, store owners!") │ ├── guides/ ← LEVEL 3: Surface │ │ ├── index.mdx ← Surface landing (list of all guides) │ │ ├── getting-started.mdx ← LEVEL 4: Leaf │ │ ├── setting-up-points.mdx │ │ ├── customizing-rewards.mdx │ │ └── importing-existing-customers.mdx │ ├── tutorials/ │ │ ├── index.mdx │ │ ├── first-loyalty-campaign.mdx │ │ └── holiday-promotions.mdx │ ├── help/ ← help center articles │ │ ├── index.mdx │ │ ├── troubleshooting-points-not-showing.mdx │ │ ├── billing-faq.mdx │ │ └── uninstall-and-data-export.mdx │ ├── knowledge-base/ ← searchable FAQ / KB │ │ ├── index.mdx │ │ ├── how-points-expire.mdx │ │ └── supported-currencies.mdx │ └── glossary.mdx ← product-specific glossary terms │ ├── developer/ ← LEVEL 2: Track │ ├── _track.json │ ├── index.mdx │ ├── quickstart.mdx │ ├── architecture-overview.mdx │ ├── api/ ← LEVEL 3: Surface │ │ ├── index.mdx ← API overview + authentication │ │ ├── openapi.yaml ← OpenAPI 3.x spec (Mintlify renders this) │ │ ├── customers.mdx ← LEVEL 4: Leaf (per-endpoint page) │ │ ├── points.mdx │ │ ├── rewards.mdx │ │ ├── tiers.mdx │ │ └── webhooks-reference.mdx │ ├── sdk/ │ │ ├── index.mdx │ │ ├── javascript.mdx │ │ └── react-components.mdx │ ├── webhooks/ │ │ ├── index.mdx │ │ ├── events-list.mdx │ │ └── handling-webhooks.mdx │ ├── playground.mdx ← embeds the shared playground service │ ├── guides/ │ │ ├── index.mdx │ │ ├── authentication-deep-dive.mdx │ │ ├── rate-limiting.mdx │ │ └── testing-in-development.mdx │ ├── tutorials/ │ │ ├── index.mdx │ │ ├── build-a-custom-rewards-widget.mdx │ │ └── integrate-with-existing-pos.mdx │ ├── changelog.mdx │ └── glossary.mdx │ ├── partner/ ← LEVEL 2: Track │ ├── _track.json │ ├── index.mdx │ ├── affiliate-program.mdx │ ├── commission-structure.mdx │ ├── co-marketing.mdx │ ├── reseller-agreement.mdx │ ├── guides/ │ │ ├── index.mdx │ │ └── selling-loyalty-to-merchants.mdx │ └── glossary.mdx │ └── _shared/ ← Node-level shared assets ├── snippets/ ← MDX fragments reused across Tracks │ ├── pricing-table.mdx │ └── support-contact-block.mdx ├── assets/ │ ├── loyalty-rewards-logo.svg │ ├── loyalty-rewards-screenshot-dashboard.png │ └── loyalty-rewards-screenshot-points.png └── metadata.json ← contributors, source repos, SLAs ``` ### 3d. Depth Rules (Hard Caps) | Level | What It Represents | Example Path | | ----- | ---------------------------- | ------------------------------------------------------------------- | | 1 | Category + Node slug | `nodes/shopify/loyalty-rewards/` | | 2 | Track | `nodes/shopify/loyalty-rewards/merchant/` | | 3 | Surface | `nodes/shopify/loyalty-rewards/merchant/guides/` | | 4 | Leaf (content file) | `nodes/shopify/loyalty-rewards/merchant/guides/getting-started.mdx` | | 5 | **MAXIMUM for sub-sections** | `nodes/shopify/loyalty-rewards/developer/api/v2/customers.mdx` | | 6 | **NEVER ALLOWED** | If you reach level 6, STOP. The Node must be split. | **What to do when you hit the depth cap:** * If you have a folder that would be at level 5 and it needs sub-folders, that is a signal the Node is too large. * Split the Node into two Nodes. Example: if the Loyalty app's API grows to have separate v1 and v2 versions with completely different endpoint sets, create `nodes/shopify/loyalty-rewards-v1/` and `nodes/shopify/loyalty-rewards-v2/` as separate Nodes. * If the content just needs grouping within a level-4 leaf, use `section:` frontmatter tags inside the MDX file instead of creating a new folder. **Common mistake to avoid:** Do not create folders like `nodes/shopify/loyalty-rewards/developer/api/customers/endpoints/create.mdx`. The `customers.mdx` file at level 4 should contain all endpoints for the Customers resource. If the file gets too long (over 500 lines), split by resource, not by action: `customers.mdx`, `points.mdx`, `rewards.mdx` — all at level 4. *** ## 4. Hub Rules ### 4a. What Justifies a Hub A Hub exists when two or more Nodes meet **at least two** of these five criteria: 1. **Data flow** — products read from or write to each other's APIs or databases. 2. **Shared industry** — both serve the same merchant vertical (Shopify merchants, accountants, restaurants, etc.). 3. **Shared authentication** — single sign-on or shared user identity. 4. **Marketed as a bundle** — sold together or priced as a package. 5. **Shared support SLA** — one support team handles issues across both. ### 4b. Examples of Valid Hubs * `hubs/shopify-ecosystem/` — groups the Loyalty app, any future Shopify apps, theme extensions, POS integration. Criteria met: data flow + industry + auth. * `hubs/small-business-stack/` — groups bookkeeping + merchant processing + strategic planning services. Criteria met: industry + bundle. * `hubs/merchant-omnichannel/` — groups Shopify apps + POS + mobile merchant app. Criteria met: data flow + bundle + shared auth. ### 4c. Hub Membership * A Node can belong to **multiple Hubs**. * A Node exists exactly **once** as a folder under `nodes/`. It is referenced from Hubs via the `hubs:` frontmatter array in its files — never duplicated. * Every Node declares one "home" Hub in its `scope.json` → `home_hub` field. This determines which Hub the "Back to Hub" breadcrumb points to. ### 4d. Hub Content Rules * Hub landing pages (`hubs//index.mdx`) are **90% auto-generated** from a query over all Nodes that list that Hub in their `hubs:` frontmatter. * The remaining **10%** is a hand-written introduction (2-4 paragraphs) explaining the ecosystem. * Adding a product to a Hub is a **one-line frontmatter edit** in the Node's files — never a Hub page rewrite. ### 4e. Hub Governance Adding a new Hub requires a PR containing a `HUB_PROPOSAL.md` file in the new Hub's folder that justifies it against the five criteria. AI can draft the proposal, but only a human can merge it. *** ## 5. Node Internal Structure (The Template) ### 5a. Allowed Surfaces Per Track This is a **closed set**. Do not invent new Surfaces without a governance review. **Merchant Track surfaces:** * `index.mdx` (Track landing) * `guides/` (how-to articles) * `tutorials/` (step-by-step walkthroughs) * `help/` (help center / support articles) * `knowledge-base/` (searchable FAQ) * `glossary.mdx` (product-specific terms) **Developer Track surfaces (includes everything in Merchant, plus):** * `quickstart.mdx` (getting started in under 5 minutes) * `architecture-overview.mdx` (system design explanation) * `api/` (API reference pages + `openapi.yaml`) * `sdk/` (SDK documentation per language) * `webhooks/` (webhook events and handling) * `playground.mdx` (embeds the shared API playground) * `changelog.mdx` (version history) **Partner Track surfaces:** * `index.mdx` (Track landing) * `affiliate-program.mdx` * `commission-structure.mdx` * `co-marketing.mdx` * `reseller-agreement.mdx` * `guides/` (partner-specific guides) * `glossary.mdx` ### 5b. Required Files in Every Node These files are **mandatory** and must exist in every Node, even if they are stubs: 1. `node.json` — machine-readable manifest (see §6b for schema) 2. `index.mdx` — Node landing page 3. `scope.json` — chat scope configuration (see §8b for schema) 4. `merchant/index.mdx` — Merchant Track landing 5. `developer/index.mdx` — Developer Track landing 6. `partner/index.mdx` — Partner Track landing 7. `_shared/metadata.json` — contributor info, source repos, SLAs If a Track has no content yet, its `index.mdx` must contain a "Coming Soon" message following the standard frontmatter contract. Never leave it empty. *** ## 6. Frontmatter Contract ### 6a. The Law Every .mdx File Obeys Every Leaf has standardized frontmatter. This is what lets automation build the graph, run link checks, scope chat, generate llms.txt files, and keep everything consistent. ```yaml theme={null} --- title: "Customers API" description: "One sentence describing the page. Used in search results and llms.txt." slug: "customers" # kebab-case, no spaces, no special characters node: "shopify/loyalty-rewards" # category/node-slug — must match folder path track: "developer" # EXACTLY ONE OF: merchant | developer | partner surface: "api" # EXACTLY ONE OF the allowed surfaces for this track (see §5a) audience_level: "intermediate" # EXACTLY ONE OF: beginner | intermediate | advanced content_type: "reference" # EXACTLY ONE OF: concept | how-to | tutorial | reference | troubleshooting | faq tags: ["customers", "auth", "rest-api"] # lowercase, kebab-case, 3-10 tags recommended hubs: ["shopify-ecosystem", "merchant-omnichannel"] # which Hubs surface this Node edges: # cross-links this page declares - type: "depends-on" # EXACTLY ONE OF: depends-on | related | see-also | prerequisite target: "shopify/loyalty-rewards/developer/api/authentication" - type: "related" target: "shopify/loyalty-rewards/merchant/guides/setting-up-points" source: # ONLY for auto-generated docs; omit for hand-written repo: "PcnaidInc/Shopify-Rewards-Loyalty-App" path: "app/routes/api.public.v1.customers.ts" last_synced: "2026-05-20T02:00:00Z" generator: "sync-bot-v1" maintainer: "ai" # EXACTLY ONE OF: ai | human | hybrid review_status: "auto-generated" # EXACTLY ONE OF: draft | auto-generated | human-reviewed | locked last_reviewed: "2026-05-20" reviewed_by: "abdul@pcnaid.com" # email of the last human reviewer version: "1.0.0" # semver — follows source app version when generated llms_include: true # whether to include this page in llms.txt generation llms_priority: 3 # 1 (highest) to 5 (lowest) — controls ordering in llms.txt llms_persona: "developer" # EXACTLY ONE OF: casual | developer | partner | all --- ``` The Reviewer Bot validates `llms_priority` as an integer from 1 through 5; booleans and quoted numbers are invalid. Within each Node, the Node-level `index.mdx` must have a value less than or equal to every other page's value. Because 1 is the highest priority, this makes the Node landing page at least as high-priority as every sibling page. ### 6b. node.json Schema ```json theme={null} { "node_id": "shopify/loyalty-rewards", "display_name": "Pcnaid Loyalty & Rewards", "category": "shopify", "slug": "loyalty-rewards", "status": "active", "home_hub": "shopify-ecosystem", "hubs": ["shopify-ecosystem", "merchant-omnichannel"], "source_repos": [ { "repo": "PcnaidInc/Shopify-Rewards-Loyalty-App", "branch": "main", "sync_enabled": true } ], "tracks": ["merchant", "developer", "partner"], "created_at": "2026-05-20", "maintainer": "abdul@pcnaid.com", "compass_component_id": "optional-atlassian-compass-id" } ``` ### 6c. What the Frontmatter Enables * `node` + `track` + `surface` + `slug` → fully determines the URL. No guessing. * `edges` → nightly job builds a network-wide link graph for search, related-content sidebars, and broken-link detection. * `source` → automation knows which upstream repo triggers a regeneration. * `review_status: locked` → AI cannot overwrite this file. Human edits only. * `maintainer: hybrid` → AI drafts changes as PRs; humans approve. * `llms_include` + `llms_priority` + `llms_persona` → nightly job assembles llms.txt files. *** ## 7. Naming Conventions (Enforced by CI) These rules are checked by the Reviewer Bot on every PR. Violations block the merge. * **Folders:** `kebab-case`. Singular unless the folder is a collection (`guides/`, `tutorials/` are plural; `developer/`, `merchant/` are singular). * **Files:** `kebab-case.mdx` for content; `kebab-case.json` for config. No dates in filenames. No version numbers in filenames (versioning lives in frontmatter). * **Slugs in frontmatter:** must match the filename exactly, minus the extension. * **Node slugs:** `` (e.g., `loyalty-rewards`, NOT `Pcnaid-Loyalty-Rewards-App`, NOT `pcnaid_loyalty`). * **Hub slugs:** `` (e.g., `shopify-ecosystem`). * **Anchors in headings:** auto-generated by Mintlify, lowercase, kebab-cased. Do not manually set anchors. * **Image filenames:** `-.png` (e.g., `loyalty-rewards-dashboard-overview.png`). This prevents collisions when served from shared CDN. * **Frontmatter keys:** `snake_case` only. No camelCase, no PascalCase. * **Git branches (AI-generated):** `ai////` (e.g., `ai/shopify/loyalty-rewards/api-sync/add-customers-endpoint`). * **Commits (AI-generated):** Conventional Commits format: `docs(/): ` (e.g., `docs(shopify/loyalty-rewards): regenerate customers API reference`). * **PR titles (AI-generated):** `[AI] /: ` (e.g., `[AI] shopify/loyalty-rewards: update API docs from v1.2.0 release`). *** ## 8. Scoped Live Chat ### 8a. Three Tiers Users interact with an AI chat widget that is context-locked to where they are in the documentation: * **Namespace chat** (when user is on `/` or `namespace/` pages) — indexes the entire network. For "I don't know where to start" users. * **Hub chat** (when user is on `hubs//` pages) — indexes that Hub's intro + all linked Nodes' content. For "I know my industry but not which product" users. * **Node chat** (when user is on `nodes///` pages) — indexes only that Node's folders. For "I'm using this product and need help" users. ### 8b. scope.json Schema Every Hub and Node must have a `scope.json`. This is the configuration file that the chat system reads. ```json theme={null} { "scope_id": "node-shopify-loyalty-rewards", "scope_type": "node", "display_name": "Loyalty & Rewards Support", "include_paths": [ "nodes/shopify/loyalty-rewards/**" ], "exclude_paths": [ "**/drafts/**", "**/_shared/assets/**" ], "persona_default": "casual", "fallback_scope": "hub-shopify-ecosystem", "home_hub": "shopify-ecosystem" } ``` **Fields explained:** * `scope_id` — unique identifier. Format: `--` for Nodes, `-` for Hubs, `namespace` for the root. * `scope_type` — `node`, `hub`, or `namespace`. * `include_paths` — glob patterns for folders this scope retrieves from. * `exclude_paths` — glob patterns to exclude (drafts, binary assets, etc.). * `persona_default` — the default audience level for chat responses: `casual`, `technical`, or `partner`. * `fallback_scope` — if the chat can't answer from this scope, which parent scope to try next. Nodes fall back to their home Hub; Hubs fall back to `namespace`. * `home_hub` — which Hub's breadcrumb this Node shows. Required for Nodes; omitted for Hubs. ### 8c. Chat Implementation The chat widget is **Mintlify's built-in AI chat**, configured at the workspace level. Mintlify's chat automatically uses the page context (which Node/Hub the user is on) to scope its retrieval. No custom chat backend is needed. If Mintlify's built-in chat is insufficient for a specific scope, a secondary option is the **Rovo Docs Agent** in Atlassian Studio, scoped to the matching Confluence space (see §10). *** ## 9. llms.txt / llms-full.txt Rules ### 9a. What These Files Are `llms.txt` is a slim, structured index of documentation links and descriptions, designed for AI tools to quickly understand what documentation exists. `llms-full.txt` is a complete Markdown export of the documentation content, designed for IDE integrations and agent workflows that can process large inputs. ### 9b. Placement Rules | Location | Files Generated | Pattern Used | Purpose | | ------------------------------------------ | ---------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `/namespace/` | `llms.txt` + `llms-full.txt` | Index + Export (Anthropic/Vercel) | Global map of all Hubs and Nodes; full export for IDE/agent ingestion | | `/hubs//` | `llms.txt` only | Catalog (Stripe/Cloudflare) | Curated entry points into that ecosystem's Nodes. No full export — too much overlap with Node-level exports | | `/nodes///` | `llms.txt` + `llms-full.txt` | Index + Export | Product-specific index and full content export | | Track-level (e.g., `/nodes/.../merchant/`) | `llms.txt` only | Focused Workflow (Cursor/Windsurf) | Role-scoped entry points for that persona | ### 9c. Generation Rules * **All llms.txt and llms-full.txt files are auto-generated.** Never hand-write them. * The generation job runs nightly as a GitHub Actions workflow (`llms-txt-generator.yml`). * Content is assembled from frontmatter fields: `llms_include`, `llms_priority`, `llms_persona`, `title`, `description`, and `slug`. * Pages with `llms_include: false` are excluded. * Pages are ordered by `llms_priority` (1 = first, 5 = last). * Pages are filtered by `llms_persona` to the appropriate Track-level llms.txt. ### 9d. llms.txt Format ``` # Pcnaid Loyalty & Rewards — Documentation > Pcnaid's loyalty and rewards app for Shopify. Points, tiers, referrals, and custom rewards for merchants. ## Getting Started - [Quickstart](https://docs.pcnaid.com/shopify/loyalty-rewards/developer/quickstart): Set up the Loyalty app in under 5 minutes - [Merchant Setup Guide](https://docs.pcnaid.com/shopify/loyalty-rewards/merchant/guides/getting-started): Configure points and rewards for your store ## API Reference - [Customers API](https://docs.pcnaid.com/shopify/loyalty-rewards/developer/api/customers): Create, read, update customer loyalty profiles - [Points API](https://docs.pcnaid.com/shopify/loyalty-rewards/developer/api/points): Award, redeem, and query point balances ## Webhooks - [Events List](https://docs.pcnaid.com/shopify/loyalty-rewards/developer/webhooks/events-list): All webhook events the app emits ## Help & Support - [Troubleshooting](https://docs.pcnaid.com/shopify/loyalty-rewards/merchant/help/troubleshooting-points-not-showing): Common issues and solutions - [Billing FAQ](https://docs.pcnaid.com/shopify/loyalty-rewards/merchant/help/billing-faq): Pricing, plans, and payment questions ``` *** ## 10. Atlassian Integration Pcnaid has a full Atlassian stack. These tools supplement the GitHub-based documentation network — they do not replace it. GitHub is always the source of truth for published documentation. ### 10a. Tools and Their Roles | Atlassian Tool | Role in Documentation Network | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Confluence Premium** | Authoring and staging for non-technical content. WYSIWYG editing for merchant and partner Tracks. Synced to GitHub via nightly Confluence-to-Markdown workflow. | | **Jira Premium** (23 existing spaces) | Documentation work tracker. Every doc update = a Jira ticket. AI creates tickets; Abdul approves and closes. | | **Bitbucket Premium** | Read-only mirror of the GitHub `documentation` repo. Auto-synced. Not the primary. | | **Compass** | Service catalog. Every Node and Hub is registered as a Compass Component with health scorecards. | | **JSM (Jira Service Management)** | Help Center backend for customer-facing support. Each Node's `help/` surface embeds the JSM portal filtered by product. | | **Rovo Studio** | Custom AI agents scoped to Confluence knowledge. Secondary chat option alongside Mintlify's built-in chat. | | **Loom Business+AI** | Tutorial videos embedded in docs. AI transcripts auto-indexed for search. | | **Statuspage** | One Statuspage per Hub (ecosystem-level status). Embedded in Hub landing pages. | | **Trello** | Lightweight public-facing product roadmaps per Hub. | | **Goals** | Track documentation coverage KPIs (% of Nodes fully populated, freshness scores, etc.). | ### 10b. Rovo Agent Roster These pre-built Atlassian agents are available and should be activated: * **Pcnaid Docs Agent** — scoped to all 23 Pcnaid Confluence spaces. Answers questions about internal docs. * **Release Notes Drafter** — triggered by Jira tickets with "Done" status. Drafts changelog entries. * **User Manual Writer** — long-form casual documentation generation. * **Brand Voice Crafter** — enforces Pcnaid tone and style on drafted content. * **Job Listing Assistant** — for hiring documentation (contractor job posts, etc.). ### 10c. Authoring Flow 1. **Draft** in Confluence (using Pcnaid Confluence spaces) or directly in Markdown. 2. **Track** as a Jira ticket in the matching Pcnaid Jira space (PCNCM, PCNDM, etc.). 3. **Assist** with Rovo agents for AI drafting help. 4. **Publish** via PR to `github.com/PcnaidInc/documentation`. 5. **Render** by Mintlify at `docs.pcnaid.com`. 6. **Mirror** auto-pushed to Bitbucket (read-only). *** ## 11. The Linking System ### 11a. Three Link Types * **Hard links** (`edges` in frontmatter) — machine-verified. The Reviewer Bot checks that every `target` in an `edges` array resolves to an existing file. If the target doesn't exist, the PR is blocked. * **Soft links** (inline Markdown links in prose) — the nightly link checker flags 404s in a report. Does not block PRs, but generates a Jira ticket. * **External links** — checked weekly. Each external link gets a `last_verified` timestamp in the link graph database. ### 11b. Edge Types | Edge Type | Meaning | Display | | -------------- | ---------------------------------------------- | ------------------------------------ | | `depends-on` | This page requires the target to be read first | "Prerequisites" sidebar section | | `prerequisite` | Same as depends-on, reverse direction | Auto-generated from depends-on edges | | `related` | Thematically similar content | "Related Pages" sidebar section | | `see-also` | Loosely connected, good for further reading | "See Also" section at page bottom | ### 11c. Back-Link Rules * Every Node links to every Hub that references it. This is auto-maintained by the Hub Rebuilder. * Every Hub landing page is auto-generated from a query over Nodes that list it in their `hubs:` frontmatter. * Every Node and Hub has a persistent "Back to Pcnaid Documentation" breadcrumb pointing at `namespace/`. Non-negotiable. * Every page within a Node has breadcrumbs: `Pcnaid Docs > [Hub] > [Node] > [Track] > [Surface] > [Page Title]`. *** ## 12. Automation Architecture ### 12a. Six Automation Pillars Each is a separate GitHub Actions workflow file. Failures are isolated — one bot failing does not block others. **1. Sync Bot** (`nightly-sync.yml`) * Runs nightly at 02:00 CT. * For every registered source repo (declared in `node.json > source_repos`), pulls the latest code, diffs against last sync. * Feeds changed files + context to Claude or Codex (via OAuth) with the product-specific system prompt from `automation/prompts/sync-bot.md`. * Produces PRs against `PcnaidInc/documentation` grouped by Node. * PRs never auto-merge. Max 1 open AI-PR per Node at any time. **2. Reviewer Bot** (`reviewer-bot.yml`) * Triggered on every AI-generated PR. * Runs: frontmatter validator, link checker, naming convention linter, depth-cap checker, style-guide linter, and a lightweight LLM "does this read well" pass. * Auto-approves only if ALL checks pass AND changes are restricted to files with `maintainer: ai` or `hybrid`. * Never auto-approves `locked` files. Flags them for human review. **3. Hub Rebuilder** (`hub-rebuilder.yml`) * Triggered whenever a Node's `hubs:` frontmatter changes. * Regenerates affected Hub landing pages from templates in `automation/templates/`. * Must complete in under 60 seconds. **4. Link Graph Builder** (runs as part of `nightly-sync.yml`) * Crawls every Leaf's frontmatter, extracts all `edges`. * Rebuilds `data/graph.sqlite`. * Outputs a JSON export at `namespace/graph.json` for frontend consumption. **5. Freshness Monitor** (`freshness-monitor.yml`) * Runs weekly (Mondays at 08:00 CT). * Flags any Leaf with `last_reviewed` older than 180 days. * Creates a Jira ticket in the relevant Pcnaid space for each stale page. * Posts a summary report as a GitHub Actions artifact. **6. llms.txt Generator** (`llms-txt-generator.yml`) * Runs nightly after the Sync Bot completes. * Reads all frontmatter, assembles llms.txt and llms-full.txt files per the rules in §9. * Commits the regenerated files directly to `main` (no PR needed — these are fully deterministic outputs). **7. Confluence Sync** (`confluence-sync.yml`) * Runs nightly. * For Confluence pages flagged for export (via Confluence label `sync-to-docs`), converts to Markdown and creates/updates PRs. * Handles image downloads and re-paths them to `_shared/assets/`. ### 12b. Trigger Sources * **GitHub webhook** on every Pcnaid source repo → enqueues a sync job. * **Scheduled cron** for nightly batch sync (catches anything webhooks missed). * **Manual trigger** — `gh workflow run nightly-sync` for any Node. * **On-release trigger** — a source repo cutting a semver release always triggers sync. * **Drift alarm** — if a Node hasn't been synced in 7 days despite commits in its source repo, creates a high-priority Jira ticket. ### 12c. Rate Limiting * Max 1 open AI-PR per Node at any time. * If a new sync job runs while an AI-PR is open, the new changes are rebased onto the existing PR. * If the rebase fails (merge conflict), the old PR is closed and a new one is created with a comment linking to the closed PR. *** ## 13. Audience-Aware Content Rules ### 13a. Track-Specific Writing Rules * **Merchant Track** — single-column prose. Heavy screenshots. No JSON. No code blocks longer than 3 lines. Every page starts with a "What does this do for me?" section. Reading level: 8th grade or below. * **Developer Track** — dual-column asymmetric layout for API pages (Mintlify's 60/40 split with dark code column). Code-first examples. Assumes Git, terminal, and HTTP literacy. Every API page includes a working `curl` example. * **Partner Track** — prose plus tables. Revenue projections, commission schedules, case studies. No code. Includes downloadable PDF versions of legal documents (generated from the Markdown source). ### 13b. Cross-Track Linking Rule Every guide can (and should) link to its counterpart on another Track. A merchant guide explaining "what webhooks are" links to the developer deep-dive; the developer page links back to the plain-English merchant version. These are `related` edges in frontmatter. *** ## 14. Failure Modes & Safeguards | Failure | Mitigation | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Runaway AI generation** | Sync Bot capped at 1 open PR per Node. Queue backups create a Jira alert. | | **Contradictory human + AI edits** | Humans always win merge conflicts. AI PRs are rebased, not force-pushed. | | **Source repo deleted** | Sync jobs fire a "tombstone" alert. Node is NOT auto-deleted. Manual archive only. | | **Broken external links** | Weekly check produces a report. Never auto-removes links. | | **LLM hallucination** | Every AI-generated file has `review_status: auto-generated`. UI renders a "This page was AI-generated" banner until a human sets `review_status: human-reviewed`. | | **Search poisoning** | Mintlify's AI assistant prioritizes `human-reviewed` and `locked` pages over `auto-generated` pages. | | **SQLite corruption** | All SQLite files are rebuilt from source data (frontmatter + content). If corrupted, delete and re-run the nightly job. No data loss possible. | | **GitHub Actions quota exhaustion** | Monitor Actions minutes via the billing API. Alert when 80% consumed. Reduce frequency of non-critical jobs (freshness monitor → biweekly). | | **Mintlify build failure** | Mintlify builds are isolated from the Git repo state. A bad MDX file blocks rendering but not the repo. The Reviewer Bot's frontmatter validator catches most MDX errors before merge. | *** ## 15. Governance (Human-in-the-Loop Checkpoints) AI maintains the network, but humans control these gates: 1. **Adding a new top-level category** under `nodes/` — human only. 2. **Adding a new Hub** — human only (AI drafts the `HUB_PROPOSAL.md`). 3. **Adding a new Track** beyond the three defined (merchant/developer/partner) — human only. This has never been needed and likely never will be. 4. **Adding a new Surface** to the closed set — human only. 5. **Marking a file as `review_status: locked`** — human only. 6. **Merging any PR that touches `architecture/STANDARD.md`** — human only. 7. **Merging any PR that touches `namespace/`** — human only. 8. **Changing the frontmatter contract or naming conventions** — human only. 9. **Deleting any Node or Hub** — human only. 10. **Configuring API keys or OAuth tokens for external services** — human only. Everything else — creating new Nodes, new Leaves, updating existing Leaves, regenerating references, rebuilding link graphs, generating llms.txt files — AI can do autonomously as long as the PR passes the Reviewer Bot. *** ## 16. Shared Infrastructure Rules **One Mintlify workspace** hosts the entire network. Mintlify charges per workspace, not per product. Use folder routing, not multiple workspaces. **One API playground backend** (`playground.pcnaid.com`) — a single Cloudflare Worker or GitHub Pages-hosted tool that proxies "Try It" requests. Each API reference page embeds it with `?node=shopify/loyalty-rewards&api=v1`. Zero per-Node code. **One search index** — Mintlify's built-in search. `node` and `track` frontmatter become filter facets. **One CDN** — Cloudflare in front of `docs.pcnaid.com`. Images and assets under `shared/assets/` or `nodes///_shared/assets/`. **One OpenAPI renderer** — Mintlify renders every Node's `openapi.yaml`. No per-Node tooling. **One CI/CD pipeline** — GitHub Actions. One workflow file per automation pillar. **One version control repo** — `PcnaidInc/documentation`. Monorepo. CODEOWNERS routes reviews. *** ## 17. Rollout Phasing 1. **Phase 0 — Foundations** (week 1): Stand up `PcnaidInc/documentation` with the full folder skeleton, `namespace/` landing page, one pilot Node (Shopify Loyalty & Rewards), the frontmatter contract, CI with the Reviewer Bot in dry-run mode, and `architecture/STANDARD.md` (this file). 2. **Phase 1 — First Node Live** (weeks 2-3): Fully populate the Loyalty & Rewards Node across all three Tracks. This validates the template end-to-end. Deploy to `docs.pcnaid.com` via Mintlify. 3. **Phase 2 — First Hub Live** (week 4): Create `hubs/shopify-ecosystem/` with the Loyalty Node referenced. Hub Rebuilder automation proven. llms.txt generation proven. 4. **Phase 3 — Automation Live** (weeks 5-6): Sync Bot starts producing AI-PRs from the source repo. Reviewer Bot moves from dry-run to enforcing. Freshness Monitor active. Confluence Sync active. 5. **Phase 4 — Scale** (ongoing): Add each additional Node one at a time. Each follows the same template. AI handles bulk population. Humans review. New Hubs created as Node count justifies them. *** ## 18. Quick Reference for AI Models If you are an AI model working on this repository, here is your checklist: 1. ✅ Read this entire STANDARD.md before starting any work. 2. ✅ Clone the Node template structure from §3c when creating a new Node. 3. ✅ Use the exact frontmatter schema from §6a — no extra fields, no missing fields. 4. ✅ Follow naming conventions from §7 — the Reviewer Bot will reject your PR if you don't. 5. ✅ Check the depth cap from §3d — if you're creating a level-6 folder, stop and split the Node. 6. ✅ Declare all cross-references as `edges` in frontmatter, not just inline links. 7. ✅ Set `review_status: auto-generated` on everything you create. Never set `human-reviewed` or `locked`. 8. ✅ Set `maintainer: ai` on files you create. Set `maintainer: hybrid` if a human asked you to update an existing file. 9. ✅ Use Conventional Commits format for commit messages. 10. ✅ Limit to 1 open PR per Node. 11. ❌ Do NOT use startup credits or API keys for documentation tasks. Use OAuth-authenticated GitHub integrations only. 12. ❌ Do NOT create external databases. Use SQLite files under `/data/`. 13. ❌ Do NOT add new categories, Hubs, Tracks, or Surfaces without human approval. 14. ❌ Do NOT delete or overwrite `locked` files. 15. ❌ Do NOT auto-merge PRs. *** *End of Architecture Standard v1.1*