---
title: "Adopt Shared Documentation Instructions"
description: "Add shared policy and authoring skill references to an owning project's AGENTS.md without copying the shared standards."
sidebar:
  order: 10
archetype: "how-to"
project: "portal"
tags: ["governance", "agents", "template"]
---

# Adopt Shared Documentation Instructions

## Prerequisites

An owning project with an AGENTS.md file, or permission to create one. Read the
[documentation policy](../policies/documentation-policy.md) and
[document-authoring skill](../skills/document-authoring/SKILL.md).
This template is an agent-instruction source, not an API specification.

## Step-by-Step Implementation

### 1. Add the shared block

Copy the following block into the project's root AGENTS.md, preserving unrelated
instructions. Replace an existing documentation block rather than adding a
second, conflicting copy. Apply it to documentation and JSDoc work without a
separate user reminder.

```markdown
## Documentation

For all documentation and JSDoc work in this project, read and follow
these shared standards without requiring a separate user reminder:

- Policy: https://tech-docs.alneas.com/policies/documentation-policy.md
- Skill: https://tech-docs.alneas.com/skills/document-authoring/SKILL.md

Apply them to repository READMEs, npm package READMEs, guides and public JSDoc.
Keep GitHub/npm READMEs in plain Markdown, with these first five H2 sections:
Elevator Pitch; Why & Value; Key Highlights; Quickstart; Next Steps.
Use 3-4 highlights. Package Quickstarts install the package name and demonstrate
an exact supported public import, with required peers, styles and host setup.
README links must work in the repository and package distribution. Use canonical
HTTPS documentation links when a target is outside the npm payload.
Generate portal metadata wrappers from the README; never maintain two introductions.
Run the project's README/documentation checks before submitting changes.
For generated documentation, implement temporary-regeneration freshness checks
and connect them to the existing documentation/CI gate if missing. Follow the
shared skill's implementation procedure; copying a checker is not integration.
Do not claim a GitHub or npm README is updated until that destination is verified.

Use these public references; a sibling github-docs checkout is not required.
Keep canonical English project guides and JSDoc in this project. Declare
approved public documents and API entrypoints in docs.manifest.json for
one-way ingestion by github-docs.

The github-docs project owns portal navigation, Japanese portal translations
and generated portal API pages. Do not reproduce those outputs here.
Preserve project-owned UI strings and runtime assets separately from portal
translations. Exclude private guides, unapproved drafts, customer/operator
evidence and secrets from public documentation and package artifacts.

```

### 2. Add verified project-specific details

Append only facts verified in that project. The following is an example for a
project that actually uses these paths and command; adapt or omit each line.
Do not add a validation command or manifest that the project does not have.

```markdown
### Project-specific documentation

- Canonical guides: docs/
- API documentation: source JSDoc
- Public ingestion manifest: docs.manifest.json
- Documentation validation: bun run docs:check
```

Keep shared standards at their public policy and skill URLs. Do not copy their
bodies into each project or establish an upstream portal/translation runtime.
This template is onboarding material: AGENTS.md retains the short reference block,
not the full template. Existing projects need changes when references, scope or
project-specific details change; routine policy edits remain in the shared sources.

## Verification

### README validation

Copy the [portable checker](readme/check-readmes.mjs) and
[regression tests](readme/check-readmes.test.mjs) into the owning project's
`scripts/` directory. Adapt the [target list](readme-policy.example.json) as
`readme-policy.json`, including the repository README and every distributed
package README. Keep a reviewed local copy so CI does not fetch executable code.
The common checker is maintained here; project configuration contains only verified paths.
The checker rejects an unregistered package README. An unreleased private stub
may be excluded only with an explicit reason; public packages cannot use that
exception. Remove the exception and provide its README before distribution.

Run `node --test scripts/check-readmes.test.mjs` and
`node scripts/check-readmes.mjs` from the project root, and include both in the
existing documentation/CI gate. Do not replace stronger project-specific checks.

The checker verifies plain Markdown, section order and nonempty sections, 3-4
highlights, setup commands, package installation/import targets, next-step links
and relative-link/package-file boundaries. Review factual claims, prerequisite
completeness and runnable examples separately; structural success does not certify
JSDoc completeness, runtime behavior or registry publication. Check the actual
packed README and its links before a release, and compare the published README
with its source after an authorized publication. Never republish a package merely
to make a documentation check pass.

- The project instruction file names `document-authoring` through its public URL.
- Policy and skill references use the same public origin and no sibling checkout path.
- Documentation and JSDoc are covered without a separate user reminder.
- Project paths, manifest and validation commands match the actual project.
- Public ingestion includes only approved sources; confidential material stays excluded.
- Run the project's own documentation checks. If an external reference cannot be
  read, report that limitation; do not claim to have applied an unread revision.

### Generated-output freshness

Follow the [generated documentation check setup](generated/README.md) to detect
stale README-derived pages, exports references, manifests and AI indexes.
Copy the shared checker and tests into the project, add temporary-output support
to its generator, declare its command/output paths in `generated-policy.json`,
and connect the check to the existing documentation/CI gate. The shared checker
does not provide the project-specific generator adaptation. Keep normal
generation and freshness checking separate so validation reports drift without
repairing it.

## Troubleshooting / Common Pitfalls

- An old `alneas-documentation` instruction: replace it with the `document-authoring`
  reference above; do not treat the old name as a separate available skill.
- Conflicting nested AGENTS.md rules: align the applicable documentation blocks,
  preserving project-specific constraints and unrelated instructions.
- A changed public domain: update the template and project reference blocks only
  after the new endpoints are available; preserve old URLs through redirects.
- Missing local validation: state the actual check or its absence instead of
  inventing a generic command.