Skip to content

chore: add AGENTS.md #170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
strantalis wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore: add AGENTS.md #170

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Repository Guidelines

## Project Structure & Module Organization

- `docs/`: Documentation content in Markdown/MDX (for example `docs/getting-started/index.mdx`).
- `src/`: Docusaurus site code (React/TypeScript), including OpenAPI tooling in `src/openapi/`.

Check failure on line 6 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'assertation' instead of 'Docusaurus'.

Raw Output:
{"message": "[Vale.Terms] Use 'assertation' instead of 'Docusaurus'.", "location": {"path": "AGENTS.md", "range": {"start": {"line": 6, "column": 11}}}, "severity": "ERROR"}
- `specs/`: Vendored OpenAPI YAML files (inputs to generated API docs).

Check failure on line 7 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'FQN' instead of 'API'.

Raw Output:
{"message": "[Vale.Terms] Use 'FQN' instead of 'API'.", "location": {"path": "AGENTS.md", "range": {"start": {"line": 7, "column": 62}}}, "severity": "ERROR"}

Check failure on line 7 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Vendored'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Vendored'?", "location": {"path": "AGENTS.md", "range": {"start": {"line": 7, "column": 13}}}, "severity": "ERROR"}
- `static/`: Images and other static assets served as-is.
- `blog/`, `code_samples/`: Blog posts and reusable examples/snippets.

## Build, Test, and Development Commands

- `nvm use`: Use the Node version from `.nvmrc` (CI uses Node 22).
- `npm ci`: Install dependencies from `package-lock.json`.
- `npm run start`: Run the local Docusaurus dev server.

Check failure on line 15 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'dev'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'dev'?", "location": {"path": "AGENTS.md", "range": {"start": {"line": 15, "column": 45}}}, "severity": "ERROR"}

Check failure on line 15 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'assertation' instead of 'Docusaurus'.

Raw Output:
{"message": "[Vale.Terms] Use 'assertation' instead of 'Docusaurus'.", "location": {"path": "AGENTS.md", "range": {"start": {"line": 15, "column": 34}}}, "severity": "ERROR"}
- `npm run build`: Full build (runs `check-vendored-yaml`, generates OpenAPI docs, then builds to `build/`).
- `npm run gen-api-docs-all`: Generate OpenAPI docs (writes under `docs/OpenAPI-clients/` when present/needed).
- `npm run check-vendored-yaml`: Verify vendored OpenAPI YAML matches upstream.

Check failure on line 18 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'vendored'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'vendored'?", "location": {"path": "AGENTS.md", "range": {"start": {"line": 18, "column": 41}}}, "severity": "ERROR"}
- `npm run update-vendored-yaml`: Refresh vendored specs in `specs/` from upstream.

Check failure on line 19 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'vendored'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'vendored'?", "location": {"path": "AGENTS.md", "range": {"start": {"line": 19, "column": 43}}}, "severity": "ERROR"}

Docs-only checks:
- `vale sync`: Install Vale styles configured in `.vale.ini`.
- `git diff --name-only | xargs vale --glob='!blog/*'`: Lint changed docs (matches CI’s “added lines” behavior closely).

## Coding Style & Naming Conventions

- Indentation: 2 spaces; newlines: LF (see `.editorconfig`).
- Docs: prefer `.mdx`; name new pages `kebab-case.mdx`, and use `index.mdx` for section landing pages.
- Keep long examples in `code_samples/` and reference them from docs instead of duplicating.

## Testing Guidelines

- There is no dedicated unit test runner; CI primarily validates `npm run build` and Vale.
- If you touch `docs/getting-started/` Docker Compose instructions, sanity-check them locally when feasible.

## Commit & Pull Request Guidelines

- Commits follow Conventional Commits as seen in history: `feat(docs): …`, `fix(docs): …`, `chore(deps): …`.
- PRs should include: a clear summary, linked issue/ticket when applicable, and screenshots for layout/theme changes.
- Generated content: treat `docs/OpenAPI-clients/` as derived output; prefer updating `specs/` via `npm run update-vendored-yaml`.
- CODEOWNERS: changes to `package.json` / `package-lock.json` require review from `@opentdf/security` in addition to maintainers.
Loading