AGENTS.md

AGENTS.md

Instructions for AI coding agents operating in this repository.

Project Overview

Docusaurus 3 static documentation site (lucanerlich.com). Content covers AEM, Java, JavaScript, Strapi, and software design patterns. There is almost no application code -- the repo is primarily Markdown/MDX docs with minimal TypeScript/JS configuration and CSS.

• Framework: Docusaurus 3.9.x (@docusaurus/preset-classic)
• Package manager: pnpm 10.x (see packageManager in package.json)
• Node version: ^22 (ignore the outdated .nvmrc which says v16)
• React: 19.x
• TypeScript: ~5.9.x
• Deployment: Docker multi-stage build, served via Coolify on port 3000

Build / Dev / Serve Commands

pnpm install          # Install dependencies (always use pnpm, never npm/yarn)
pnpm start            # Local dev server with hot reload
pnpm build            # Production build (strict: throws on broken links/anchors)
pnpm serve            # Serve production build locally
pnpm run coolify      # Serve on port 3000 (production Docker target)
pnpm run clear        # Clear Docusaurus cache (.docusaurus/)

Testing

There is no test framework configured. No unit tests, integration tests, or E2E tests exist. The only verification is pnpm build, which fails on:

• Broken internal links (onBrokenLinks: 'throw')
• Broken anchors (onBrokenAnchors: 'throw')
• Broken markdown links and images (via markdown.hooks)

Always run pnpm build after making changes to verify nothing is broken.

Prose Linting

Vale is configured for prose linting (.vale.ini):

vale docs/path/to/file.md    # Lint a single file
vale docs/                    # Lint all docs

Styles: Microsoft, write-good, Vale built-ins. Applied to *.md and *.mdx.

Code Style Guidelines

Formatting (enforced via .editorconfig)

• Indentation: 4 spaces (all files)
• Line endings: LF (Unix-style)
• Charset: UTF-8
• Final newline: Always insert trailing newline
• No ESLint or Prettier is configured; follow existing patterns

TypeScript / JavaScript

• Use import type for type-only imports (see docusaurus.config.ts line 1-2)
• Use single quotes for strings
• Use trailing commas in arrays and object literals
• Use satisfies for type narrowing where appropriate
• Use explicit type annotations for exported values
• Prefer const over let; avoid var
• JSDoc comments with @ts-check for .js files (see sidebars.js)
• CommonJS (module.exports) for .js config files consumed by Docusaurus
• ES modules (export default) for .ts config files
• Section separators use comment blocks with dashes:

  // ------------------------------------------------------------------
  // Section name
  // ------------------------------------------------------------------

CSS

• Use CSS custom properties (--custom-*) for theme tokens
• Light/dark mode via html[data-theme='dark'] selector
• Override Infima framework variables, do not fight the framework
• 4-space indentation, consistent with .editorconfig

Markdown / MDX Content

• Frontmatter fields: title, description, slug, tags, keywords, sidebar_position, sidebar_label (not all required on every page)
• File extensions: .md for plain Markdown, .mdx for files using JSX/components (Docusaurus markdown.format: 'detect' handles both automatically)
• Headings: Start content with # Title (H1), use H2/H3 for sections
• Code blocks: Always include a language tag (java, typescript, etc.)
• Diagrams: Use Mermaid fenced code blocks (```mermaid)
• Links: Use relative paths to other docs (./aem/architecture.mdx)
• Em dashes: Use -- (double hyphen), not the Unicode em dash character
• Categories: Define via _category_.json with label and optional generatedIndex description
• Prism languages available: groovy, java, rust, python, bash, yaml, csv (plus all Prism defaults)
• Sidebar ordering: Controlled by sidebar-order.ts, not sidebar_position frontmatter. To reorder pages, edit the arrays in that file.
• Trailing slashes: Enabled (trailingSlash: true). All internal links should end with / or use relative file paths.

Project Structure

docusaurus.config.ts   # Main site configuration (navbar, footer, plugins, redirects)
sidebar-order.ts       # Sidebar ordering constants (edit here to reorder pages)
sidebars.js            # Sidebar generator config (autogenerated from filesystem)
umami.js               # Analytics client module (self-hosted Umami)
src/css/custom.css     # Infima CSS overrides and theme tokens
src/pages/imprint.md   # Legal imprint page
docs/                  # All documentation content
  intro.md             # Homepage (slug: /)
  aem/                 # Adobe Experience Manager docs
  strapi/              # Strapi CMS docs
  javascript/          # JavaScript guides
  java/                # Java guides
  design-patterns/     # Design pattern catalog
  other/               # Misc topics (shell, SQL, Docusaurus, etc.)
  projects/            # Project showcases
static/                # Static assets (images, favicon, manifest.json)
.cursor/rules/         # 62 Cursor AI rules (performance + security)

Key Configuration Details

• Broken link checking is strict -- pnpm build will fail on any broken link, anchor, markdown link, or image reference. Always verify after edits.
• Blog is disabled (blog: false in preset config).
• Client redirects are configured in docusaurus.config.ts under the @docusaurus/plugin-client-redirects plugin. When moving/renaming docs, add a redirect from the old path to the new path.
• Algolia search is configured -- no action needed from agents.
• Future flags: experimental_faster: true (SWC) and v4: true.

Cursor Rules (.cursor/rules/)

The repo includes 62 Cursor rule files in two categories. These should be treated as project-level coding guidelines:

Performance Rules (.md files)

Organized into 8 sections: async, bundle, server, client, rerender, rendering, js, advanced. Key rules include:

• Eliminate async waterfalls (parallelize with Promise.all)
• Avoid barrel imports; use direct path imports
• Use dynamic imports / React.lazy for code splitting
• Memoize expensive computations; use useMemo / useCallback appropriately
• Hoist static JSX outside render; use conditional rendering
• Prefer Set/Map for lookups; use early returns

Security Rules (.mdc files, always applied)

Core principles enforced across all code:

• No raw user input in file access, command execution, or DB queries
• No exposed secrets in frontend code or public repos
• Validate all external input before use
• No sensitive data in logs
• Secure protocols only (HTTPS/TLS)
• No dynamic code execution (eval, new Function, etc.)
• No hardcoded credentials
• Fail securely on errors; default to secure configurations
• Apply defense in depth and least privilege

Language-specific security rules exist for: Java, Node.js, Python, Ruby, PHP, Rust, C, F#.

Common Tasks for Agents

Adding a new doc page

1. Create a .md or .mdx file under the appropriate docs/ subdirectory
2. Add frontmatter with at least title and description
3. If ordering matters, add the filename (without extension) to the appropriate array in sidebar-order.ts
4. Run pnpm build to verify no broken links

Moving or renaming a doc

1. Move/rename the file
2. Add a redirect in docusaurus.config.ts under plugin-client-redirects
3. Update any internal links referencing the old path
4. Update sidebar-order.ts if the page was listed there
5. Run pnpm build to verify

Adding a new sidebar category

1. Create the directory under docs/
2. Add a _category_.json with label and optional generatedIndex
3. Add the directory name to the parent's array in sidebar-order.ts
4. Run pnpm build to verify

Cursor Cloud specific instructions

Environment prerequisites

Node.js 22 and pnpm 10.x are required. The VM update script installs these automatically via NodeSource and corepack. No additional system dependencies are needed.

Running the dev server

pnpm start --host 0.0.0.0 --port 3000

Use --host 0.0.0.0 so the site is accessible from the Desktop browser pane. The dev server supports hot reload; editing any .md, .mdx, .ts, .css, or config file triggers an automatic rebuild.

Verification workflow

There is no test suite. The verification steps are:

1. pnpm build -- the only "test". Fails on broken links, anchors, or images.
2. pnpm start -- visually confirm the site renders correctly in a browser.

Gotchas

• No lockfile in repo: pnpm-lock.yaml is gitignored. pnpm install generates it fresh each time. This means dependency versions may drift between environments; pnpm build is the gate.
• .nvmrc says v16: Ignore it. The correct Node version is ^22 per engines in package.json.
• No ESLint / Prettier: There are no JS/TS linters configured. The only prose linter is Vale (optional, not installed in the Cloud VM by default).
• SWC build warnings: The vscode-languageserver-types critical dependency warning during pnpm build is benign and can be ignored.
• Algolia and Umami: Both are external services configured with public client-side keys. They are non-functional in local dev (Umami is skipped on localhost). No secrets are needed.