Skip to content

📘 docs(style): Adding AGENTS direction for writing style; updating all documentation #256

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

Merged
Charles Hudson (phobetron) merged 1 commit into from
May 5, 2026
Merged

📘 docs(style): Adding AGENTS direction for writing style; updating all documentation #256

Show file tree
Hide file tree
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
31 changes: 17 additions & 14 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ applicable child `AGENTS.md` from outermost to nearest in the subtree you are ed
- Keep child `AGENTS.md` files focused on local behavior. Do not duplicate root policy unless the
subtree has a local exception.

## Environment And Tooling
## Environment and tooling

- Use the Node version from [`.nvmrc`](./.nvmrc) when possible. Repository engine constraints live
in the root [`package.json`](./package.json).
Expand All @@ -29,7 +29,7 @@ applicable child `AGENTS.md` from outermost to nearest in the subtree you are ed
- Some implementations have additional runtime prerequisites or process-management expectations. See
the relevant implementation `AGENTS.md` before running local app or E2E flows.

## Repository Layout
## Repository layout

- Shared libraries and published SDK packages live under `lib/` and `packages/`.
- Reference implementations live under `implementations/`.
Expand All @@ -38,7 +38,7 @@ applicable child `AGENTS.md` from outermost to nearest in the subtree you are ed
- Generated outputs such as `dist/`, `coverage/`, `docs/`, `pkgs/`, `playwright-report/`, and
`test-results/` are not the source of truth.

## Source Of Truth
## Source of truth

Prefer editing source files and configuration:

Expand Down Expand Up @@ -67,7 +67,7 @@ Do not hand-edit generated or local-only artifacts unless the task is explicitly
- `node_modules/**`
- local `.env` files

## ESLint Discipline
## ESLint discipline

- Treat [`eslint.config.ts`](./eslint.config.ts) as an upfront design constraint, not a cleanup step
after coding.
Expand Down Expand Up @@ -96,7 +96,7 @@ Do not hand-edit generated or local-only artifacts unless the task is explicitly
- If code keeps fighting the linter, stop and rewrite the approach to match repository patterns
rather than stacking fixes.

## Validation Policy
## Validation policy

- Run the smallest meaningful validation that matches the change.
- When linting or formatting is likely needed, prefer the smallest fix-enabled command that matches
Expand All @@ -123,7 +123,7 @@ High-signal repo-wide commands:
- `pnpm format:check`
- `pnpm docs:generate`

## Failure Handling And Recovery
## Failure handling and recovery

- Do not rerun the same failing command unchanged more than once.
- Before retrying, classify the failure into one of these buckets:
Expand Down Expand Up @@ -170,18 +170,21 @@ High-signal repo-wide commands:
- what you already tried
- the smallest next action, user input, or approval needed

## Docs, Specs, And CI
## Docs, specs, and CI

- Authored supporting docs live in `documentation/`; generated TypeDoc output lives in `docs/`.
- If the repository later adds any replacement design, architecture, or specification artifacts for
the changed area, keep them aligned in the same change.
- `docs/` is generated by TypeDoc and is gitignored.
- Implementation E2E in `.github/workflows/main-pipeline.yaml` is intentionally path-filtered. If a
change should alter E2E coverage, update the workflow and keep it aligned with
change needs to alter E2E coverage, update the workflow and keep it aligned with
[CONTRIBUTING.md](./CONTRIBUTING.md).

## README And Markdown Standards
## README and Markdown standards

- Follow [`STYLE_GUIDE.md`](./STYLE_GUIDE.md) for Contentful technical writing conventions in
human-authored documentation, including READMEs, authored docs, TSDoc/JSDoc prose, and examples.
The nearest `AGENTS.md` still owns document structure, commands, and subtree-specific exceptions.
- Treat README files as maintained source-of-truth orientation for humans. Keep them aligned with
package exports, implementation scripts, local `.env.example` files, and authored documentation in
the same change as behavior or workflow updates.
Expand All @@ -190,10 +193,10 @@ High-signal repo-wide commands:
header, `Contentful Personalization & Analytics` title, subtype `<h3>`, navigation links, and
pre-release warning.
- `documentation/**/README.md` files are navigation indexes with frontmatter.
- placeholder and internal-only README files may use a plain Markdown `#` title plus explicit
- placeholder and internal-only README files can use a plain Markdown `#` title plus explicit
status or internal-use admonitions.
- Use title case for Markdown headings, preserving official product, package, API, component, hook,
and file casing.
- Use sentence case for Markdown headings, preserving official product, package, API, component,
hook, and file casing.
- Lead with reader intent and scope: what to use, when to use it, and what belongs elsewhere. Prefer
concrete implementation guidance over marketing language.
- Keep terminology consistent: "Optimization SDK Suite", "Personalization", "Analytics", "Experience
Expand Down Expand Up @@ -230,14 +233,14 @@ High-signal repo-wide commands:
- For Markdown edits, run Prettier on touched files when practical and at least run
`git diff --check` before finishing.

## Safety Rules
## Safety rules

- Never overwrite or delete ignored local files just to get a clean run.
- Do not run destructive Contentful scripts unless explicitly asked.
- Do not use broad cleanup commands such as `pm2 delete all` unless explicitly asked.
- Do not assume full cross-platform E2E is required for every change.

## Preferred Workflow
## Preferred workflow

1. Read the root `AGENTS.md`.
2. Read each applicable child `AGENTS.md` from outermost to nearest in the subtree you will edit.
Expand Down
95 changes: 47 additions & 48 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,21 +35,21 @@ gotchas.
<!-- mtoc-start -->

- [Setup](#setup)
- [Repository Map](#repository-map)
- [Common Commands](#common-commands)
- [Common Workflows](#common-workflows)
- [Change a Workspace Package](#change-a-workspace-package)
- [Change an Implementation](#change-an-implementation)
- [Run E2E for One Implementation](#run-e2e-for-one-implementation)
- [Implementation Helper Usage](#implementation-helper-usage)
- [Validation Matrix](#validation-matrix)
- [Code Style and Local Hooks](#code-style-and-local-hooks)
- [Repository map](#repository-map)
- [Common commands](#common-commands)
- [Common workflows](#common-workflows)
- [Change a workspace package](#change-a-workspace-package)
- [Change an implementation](#change-an-implementation)
- [Run E2E for one implementation](#run-e2e-for-one-implementation)
- [Implementation helper usage](#implementation-helper-usage)
- [Validation matrix](#validation-matrix)
- [Code style and local hooks](#code-style-and-local-hooks)
- [Documentation](#documentation)
- [README Depth and Render Targets](#readme-depth-and-render-targets)
- [Local Troubleshooting](#local-troubleshooting)
- [Troubleshooting CI Issues](#troubleshooting-ci-issues)
- [E2E Coverage and Environment](#e2e-coverage-and-environment)
- [License Check Failure](#license-check-failure)
- [README depth and render targets](#readme-depth-and-render-targets)
- [Local troubleshooting](#local-troubleshooting)
- [Troubleshooting CI issues](#troubleshooting-ci-issues)
- [E2E coverage and environment](#e2e-coverage-and-environment)
- [License check failure](#license-check-failure)

<!-- mtoc-end -->
</details>
Expand Down Expand Up @@ -83,7 +83,7 @@ pnpm version:pnpm

`pnpm install` also installs the local Husky hooks used during commit and push.

## Repository Map
## Repository map

| Path | Purpose |
| -------------------- | ----------------------------------------------------------------------------------- |
Expand All @@ -102,7 +102,7 @@ The most important repository-specific mechanic is this:
- The targeted `pnpm setup:e2e:<implementation>` wrappers do this refresh for you as part of E2E
setup.

## Common Commands
## Common commands

The root [`package.json`](./package.json) contains more scripts than are listed below. These are the
ones most contributors need regularly.
Expand Down Expand Up @@ -135,9 +135,9 @@ running the whole repository when the change is narrow.
Before running `pnpm implementation:lint` across the repository, run `pnpm implementation:install`
so the reference implementations have current local package tarballs installed.

## Common Workflows
## Common workflows

### Change a Workspace Package
### Change a workspace package

1. Read the nearest package or `lib/` `AGENTS.md`.
2. Make your change in the package source, tests, docs, or local harness.
Expand Down Expand Up @@ -165,7 +165,7 @@ pnpm setup:e2e:web-sdk
pnpm test:e2e:web-sdk
```

### Change an Implementation
### Change an implementation

1. Read the nearest implementation `AGENTS.md`.
2. If your change depends on freshly built local packages, run `pnpm build:pkgs` and reinstall the
Expand All @@ -181,7 +181,7 @@ pnpm implementation:run -- web-sdk_react build
pnpm implementation:run -- web-sdk_react implementation:test:e2e:run
```

### Run E2E for One Implementation
### Run E2E for one implementation

1. Create a local `.env` from the implementation's `.env.example` if the implementation expects one
and you do not already have it.
Expand All @@ -204,7 +204,7 @@ Environment notes:
- Several implementations use PM2-managed processes for local serving; stop only the relevant
implementation process rather than doing broad PM2 cleanup.

### Implementation Helper Usage
### Implementation helper usage

`implementation:run` is the shared helper used by the implementation scripts listed above.

Expand Down Expand Up @@ -256,28 +256,28 @@ Prefer the root wrapper scripts when they already match what you want to do. For
- `pnpm setup:e2e:<implementation>`
- `pnpm test:e2e:<implementation>`

## Validation Matrix
## Validation matrix

Use the smallest meaningful validation set for the change.

| Change type | Usually run | Notes |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Docs-only or markdown-only | `pnpm format:check` | Also run `pnpm docs:generate` if public API docs or linked markdown changed |
| Package or `lib/` TypeScript change | Targeted `lint`, `typecheck`, `test:unit`, and `build` | Prefer `pnpm --filter <workspace> ...` when the change is narrow |
| Built package runtime, export, dependency, or bundle change | Targeted `size:check` or root `pnpm size:check` | Bundle-size checks are currently a contributor-run validation, not a dedicated CI job |
| Package change used by an implementation | `pnpm build:pkgs`, then reinstall the affected implementation | Use `pnpm setup:e2e:<implementation>` if E2E is your next step |
| Implementation code change | `pnpm implementation:lint`, targeted implementation `typecheck`, and implementation-local tests | Some implementations have no meaningful unit tests; E2E matters more there |
| Shared build or packaging change | Broaden validation to downstream packages and at least one affected implementation | Examples: `lib/build-tools`, package exports, tarball/install flow |
| User-visible integration or runtime behavior change | Targeted implementation E2E | Choose the implementation that exercises the changed surface |
| Change type | Usually run | Notes |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Docs-only or markdown-only | `pnpm format:check` | Also run `pnpm docs:generate` if public API docs or linked markdown changed |
| Package or `lib/` TypeScript change | Targeted `lint`, `typecheck`, `test:unit`, and `build` | Prefer `pnpm --filter <workspace> ...` when the change is narrow |
| Built package runtime, export, dependency, or bundle change | Targeted `size:check` or root `pnpm size:check` | Bundle-size checks are contributor-run validation, not a dedicated CI job |
| Package change used by an implementation | `pnpm build:pkgs`, then reinstall the affected implementation | Use `pnpm setup:e2e:<implementation>` if E2E is your next step |
| Implementation code change | `pnpm implementation:lint`, targeted implementation `typecheck`, and implementation-local tests | Some implementations have no meaningful unit tests; E2E matters more there |
| Shared build or packaging change | Broaden validation to downstream packages and at least one affected implementation | Examples: `lib/build-tools`, package exports, tarball/install flow |
| User-visible integration or runtime behavior change | Targeted implementation E2E | Choose the implementation that exercises the changed surface |

When in doubt, start targeted and broaden only if the change crosses package or implementation
boundaries.

## Code Style and Local Hooks
## Code style and local hooks

This project uses [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to enforce
coding and formatting conventions. It may be useful to enable related editor plugins to have a
smoother experience when working on Optimization SDKs.
coding and formatting conventions. You can enable related editor plugins to get the same feedback
while working on Optimization SDKs.

Please review the following files to familiarize yourself with current configurations:

Expand Down Expand Up @@ -326,15 +326,15 @@ keep these artifacts aligned:
`documentation/` contains source markdown that TypeDoc publishes. `docs/` is generated output. Do
not hand-edit generated TypeDoc output.

### README Depth and Render Targets
### README depth and render targets

READMEs are orientation surfaces, not the only place every detail should live. Match depth to the
README category:
READMEs are orientation surfaces, not the only place for every detail. Match depth to the README
category:

- Application-facing package READMEs keep purpose, install, minimal setup, common options, critical
caveats, and links to guides, reference implementations, and generated API reference.
- Lower-level package READMEs explain the package's role in the SDK stack, who should use it
directly, common setup options where useful, and where exhaustive API details live.
- Lower-level package READMEs explain the package's role in the SDK stack, who uses it directly,
common setup options where useful, and where exhaustive API details live.
- Reference implementation READMEs stay procedural: what the implementation demonstrates,
prerequisites, setup, run/test commands, environment notes, and related package links.
- Internal and placeholder READMEs stay short, explicit, and status-oriented.
Expand All @@ -347,11 +347,10 @@ Package README links must work in GitHub source browsing, generated TypeDoc proj
npmjs README rendering. Use canonical generated-doc URLs for shared header navigation and verify
repo-relative links before relying on package README publish rewriting.

## Local Troubleshooting
## Local troubleshooting

- An implementation is not reflecting your latest package change: run `pnpm build:pkgs`, then
reinstall the affected implementation with
`pnpm implementation:run -- <implementation> implementation:install`.
- An implementation is not reflecting your package change: run `pnpm build:pkgs`, then reinstall the
affected implementation with `pnpm implementation:run -- <implementation> implementation:install`.
- Playwright reports a missing browser: run `pnpm playwright:install`, or use the targeted
`pnpm setup:e2e:<implementation>` wrapper.
- Playwright system dependencies are missing on Linux: run `pnpm playwright:install-deps`.
Expand All @@ -362,9 +361,9 @@ repo-relative links before relying on package README publish rewriting.
- A local port such as `3000`, `8000`, or `8081` is already in use: stop only the relevant local
process or implementation `serve` flow rather than using broad PM2 cleanup.

## Troubleshooting CI Issues
## Troubleshooting CI issues

### E2E Coverage and Environment
### E2E coverage and environment

`Main Pipeline` runs implementation E2E jobs when path filters request them for both:

Expand Down Expand Up @@ -397,13 +396,13 @@ authoritative filter list.
Skipping an implementation E2E job because its filter did not match is expected behavior, not a CI
coverage defect.

If a change should trigger an implementation E2E job but does not match the current filters, update
the path filters in `.github/workflows/main-pipeline.yaml` in the same pull request.
If a change needs to trigger an implementation E2E job but does not match the current filters,
update the path filters in `.github/workflows/main-pipeline.yaml` in the same pull request.

E2E setup does not depend on repository secrets. Each implementation creates `.env` from its own
checked-in `.env.example` file in CI, which keeps fork PR behavior aligned with internal PRs.

### License Check Failure
### License check failure

Run `license-checker` locally:

Expand Down
Loading
Loading