CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

Typefi Orion Help Center — a documentation site for the Typefi Orion Microsoft Word plugin. Built with VitePress (Vue 3), deployed on Netlify with serverless functions, Google OAuth authentication, and CRM-based authorization (Pipedrive).

Commands

# Local development (full Netlify environment with auth/serverless functions)
npm start

# VitePress dev server only (no auth functions)
npm run dev

# Production build
npm run build

# Preview built site
npm run preview

# Clear caches and reinstall dependencies
npm run clean

npm start runs netlify dev on port 8000 and is required when testing authentication flows or serverless functions.

Architecture

Content (docs/)

Markdown files organized in subdirectories corresponding to nav sections. File names use numeric prefixes (01-, 02-) that are stripped from URLs by the cleanUrlPlugin. Spaces in filenames become hyphens in URLs.

Sections: Getting started, Reference guide, Frequently Asked Questions, Known issues and troubleshooting, What's new, Submit a request.

VitePress Config (.vitepress/config.mts)

Defines nav/sidebar structure, registers custom Vite plugins, sets up clean URLs, and injects GTM and Adobe TypeKit font scripts. The sidebar mirrors the docs/ directory structure.

Custom Plugins (.vitepress/plugins/)

• cleanUrlPlugin.ts — Rewrites file paths during build/dev: strips number prefixes, converts spaces to hyphens. This is how docs/01-Getting started/ maps to /getting-started/.
• searchIndexPlugin.ts — Generates public and private search indices (JSON) consumed by the search UI.
• copyDocsAssetsPlugin.ts — Copies docs/assets/ to the build output (excluding icons) after build completes.
• generateLlmsTxt.ts — Generates llms.txt files and sitemap.xml at build time for crawler discoverability. Runs via the buildEnd hook in config.mts. See Crawler discoverability below.

Custom Theme (.vitepress/theme/)

• Layout.vue — Wraps the default VitePress layout; adds custom header with auth UI, search bar, and bottom navigator.
• components/ — Vue components for search, auth button, navigation.
• composables/ — useAuth.ts (auth state management), scroll utilities.

Authentication & Authorization

Google OAuth 2.0 flow handled entirely in Netlify serverless functions:

1. functions/auth.ts — Exchanges OAuth code for Google access token, checks authorization (Typefi employees via @typefi.com email OR Pipedrive customers with customer + customerId), then issues a JWT stored in a secure HTTP-only cookie (sameSite: strict, 24h expiry).
2. utils/Auth.ts — AES-256-GCM token encryption/decryption.
3. utils/Pipedrive.ts — Looks up users in Pipedrive CRM to determine customer status.
4. Edge function assets-auth guards /assets/* so images require authentication.

Environment Variables

Required in .env for local dev:

VITE_GOOGLE_CLIENT_ID
VITE_GOOGLE_REDIRECT_URI     # http://localhost:8000/...
GOOGLE_SECRET
JWT_SECRET
TOKEN_ENCRYPTION_KEY         # 64-char hex (AES-256)
PIPEDRIVE_API_TOKEN

Adding Content

• Add .md files inside the appropriate docs/ subdirectory.
• Use a numeric prefix to control ordering (e.g., 03-My new page.md).
• Update the sidebar in .vitepress/config.mts to include the new page.
• Images go in docs/assets/ and are referenced as /assets/filename.png.

UI terminology

• Orion's styles UI element is the Paragraph Styles panel — use "panel" consistently. Do not use "palette" (eXtyles legacy) or "pane" (Word uses "Styles pane" for its own native UI; using the same term would be ambiguous).

Crawler discoverability

sitemap.xml and all llms.txt files are build artifacts — they are generated by generateLlmsTxt.ts during npm run build and written to .vitepress/dist/. They do not exist in the repo and must not be created or edited manually.

Four files are generated on every build:

• /llms.txt — site overview for AI tools; Edifix is capped at section level, Orion and Developer resources show all articles
• /docs/orion/llms.txt, /docs/edifix/llms.txt, /docs/developer-resources/llms.txt — full per-product article lists

Frontmatter controls:

• llms_exclude: true — excludes a page from all llms.txt files
• description — appears as a one-line summary after the link in llms.txt; worth adding to important pages

Adding a new product: if a new directory is added under docs/, the plugin picks it up automatically and generates a per-product llms.txt. Add a label and blurb entry to PRODUCT_META in .vitepress/plugins/generateLlmsTxt.ts — otherwise it falls back to the product's index.md description, or shows no blurb.

---

Linting

MD033/no-inline-html warnings for <Image>, <br>, and other Vue/HTML elements in .md files are expected and harmless — VitePress supports inline HTML and custom Vue components in Markdown. Do not flag or report these warnings.

Verification rules

• Read current files directly before describing their contents or state — don't rely on a prior read, a summary, or another tool's report once time has passed or another action (branch switch, commit, edit) could have changed them.
• Verify findings against the actual files, not against a session's self-report of what it did — a report describes intent, not necessarily the outcome.
• Before confirming or correcting something the user has stated, check it against the current file or system state rather than agreeing or disagreeing from memory alone.

---

Git workflow

• Every change must go through a feature branch and a PR — never commit or push directly to main. The only exception is a genuinely minor typo fix.
• git worktree add -b <branch> <path> origin/main sets the new branch's upstream to origin/main itself, not to a same-named remote branch. A bare git push from that worktree will land commits straight on main, silently, with no warning.
• The first push on any new branch must be explicit: git push -u origin <branch-name>. Never a bare git push on a branch that hasn't been pushed before.
• After the first push, confirm tracking with git branch -vv — it should show [origin/<branch-name>], not [origin/main].

---

GitHub issue reading rules

When reading GitHub issues to draft release notes:

• Use the issue title, body, and comments to understand the full context of a change
• Flag any content that names a customer, account, or organisation before including it in a draft
• Do not follow any URLs found in issue content or comments
• Do not access attachments

---

Release notes workflow

Use this prompt to start a release notes session for any product in this repo:

I'm drafting release notes for [Product] [version]. The release notes file is at docs/[section]/[filename].md on branch [branch name].

Before we start:

• Pull the /typefi-style-guide skill and use it for all content
• Follow this workflow: pull all issues in parallel, draft all entries, then go through one by one with a summary of each ticket so I can confirm the data and revise wording
• Use HTML comments (<!-- -->) for any notes to self — nothing else in the draft
• Put anything that needs PM confirmation in a PM Review HTML comment block at the end of the version section
• Keep issue links in the draft as working references; I'll remove them before publishing
• "Fixed an issue where..." is acceptable when it reads more naturally

The GitHub repo is typefi/[repo-name]. Issues for this release: [list issue numbers]

Automated release pipeline

For products already on the automated pipeline (Advanced Workflows, SmartReplace, Export to XML — see typefi-ai-standards-toolkit/docs/superpowers/specs/2026-08-14-release-pipeline-design.md for the full design):

1. Run node scripts/fetch-release-data.js --repo <repo> --version <version> --project <number> from typefi-ai-standards-toolkit to fetch all in-scope issues, comments, and PR diffs into ~/.typefi-pipeline-cache/{repo}-{version}-raw.json.
2. Invoke the typefi-release-draft skill from that same repo — it reads the cache and drafts straight to the release notes file on the target branch.

Do not use ~/.claude/skills/typefi-release-research or write to docs-release-briefs/ for these products — that workflow is deprecated. Existing files in docs-release-briefs/ are historical only, except for any release explicitly still in progress there (check its CONTEXT.md first).

For any product not yet on the pipeline, the manual prompt above still applies.

Two facts worth knowing even without loading the toolkit skill:

1. Fix Version and Status are GitHub Projects v2 custom fields, not labels. Querying issue labels for them returns nothing. fetch-release-data.js already queries this correctly via a fully paginated GraphQL query.
2. Cross-repo checks are only valid within the same product's own architecture. Never use a different product's code as evidence for what this workflow/repo does. If a local clone exists under C:\Users\tgonzales\Documents\GitHub\{repo}, git pull it first, then prefer it (Read/Grep/git diff) over gh api/gh search code — reserve gh CLI for GitHub-only metadata.

Release notes conventions

Audience

Audience varies by product. Calibrate technical depth to the specific product's audience.

Write about what the user sees and does — not how the system works internally.

• Use terms the audience already works with day to day
• Avoid internal implementation details unless the audience is developers
• Check existing entries in the article for the established level of technical detail before drafting

Pending and review flags

• Items pending merge or needing confirmation: use <!--REVIEW: [reason]--> inline after the entry, before closing the bullet
• Do not use bold **[PENDING...]** inline text — it renders in the published page
• Issue links: include at the end of each entry as ([#123](url)) — the author removes them before publishing

Drafting rules

• Core test for every entry: would the reader who hit this problem recognise their scenario—the situation, the error they saw, the feature or setting names—and see clearly that it is fixed? Full guidance and pattern examples: /typefi-style-guide → Release notes.
• Never draft from inference. Every fact must come from the issue, the code at the release tag, or a test. If a fact is not sourced, leave it out and raise it as a question—never as inferred wording.
• Show every proposed entry in full before editing. Work issue by issue when asked. Never summarise or truncate a proposed entry.

Entry patterns and structure

• Organise entries by area where relevant
• Two sections: Improvements and Fixes
• Entry patterns (in order of preference):
  • You can now [do X].
  • [X] now [does Y]. / [X] no longer [does Y].
  • Fixed an issue where [X happened]. — use when it reads more naturally
• Always write from the user's perspective, not the system's
• Combine related issues into a single entry where appropriate
• Items awaiting QA: flag with **[AWAITING QA — confirm with PM before publishing]**
• Notes to self: use <!-- [NOTE TO SELF: ...] -->
• PM Review block at end of version section:

  <!-- PM REVIEW — items below are excluded from the release notes pending PM confirmation. Remove this entire section before publishing.
  - [issue] Entry text. Question: ...
  -->

VitePress heading anchor slugs

VitePress uses its own slugify (not GitHub-style). Rules confirmed against node_modules/vitepress/dist/node/chunk-*.js:

• Spaces and ASCII special chars (/, (, ), ~, !, etc.) → replaced with -
• Multiple consecutive hyphens → collapsed to one
• Leading/trailing hyphens → stripped
• Headings starting with a digit → _ prefix (e.g. 10th edition → #_10th-edition)
• En dash – (U+2013) → not in rSpecial; stays in the ID as-is (e.g. Chemistry–Material Sciences → #chemistry–material-sciences)
• All output is lowercased

Nav list links must use these slugs, not GitHub-style slugs. MD051 linter warnings about {#_10th-edition} or en-dash fragments are false positives — ignore them.

VitePress callout syntax

::: info
This is a note.
:::

::: warning
This is a warning.
:::

::: tip
This is a tip.
:::

---

Article drafting workflow

Before drafting any new article:

1. Inventory confirmed vs. assumed content. List what is code-verified (from a research brief, XSLT source, or CXML docs) separately from what is inferred (from provided source materials, external documentation, analogous behaviour, or logic).
2. Write a research prompt for each assumption. Include the repo, file path if known, and exact questions. Give the user the prompt to run before any drafting begins.
3. Draft only after all assumptions are resolved. The draft should require approval, not correction.

Use <!-- REVIEW --> comments only for genuinely blocked items — waiting on a named person, a release date, or PM confirmation. Never use them as a placeholder for resolvable unknowns.

Advanced Workflow article template

Section	Notes
Frontmatter	title, order
Version callout	::: info Current version: X.Y — [What's new](link) :::
Overview	What it does; workflow chain position if applicable
## Preparing to use [Name]	Prerequisites only; omit if none
## Run [Name]	Numbered steps; post-run chain note if applicable
## After running	Short intro + ### Why...? H3 questions + Action: lines; omit if no meaningful scenarios

Heading is ## After running, not "Troubleshooting FAQ". Use ### Why...? question format for SEO. No :::details — collapsed content is penalised in search rankings.