chore: add AGENTS.md

[hperl]

Add AGENTS.md with guidance on where to put what.

Summary by CodeRabbit

• Documentation
  • Added contributor-facing guidelines organizing docs by deployment model with rules for migrated content and a step-by-step workflow for updates.
  • Defined a pattern using shared reusable content plus per-deployment shell pages that appear in sidebars.
  • Established canonical URL/SEO conventions (default canonical with a self-hosted exception) and how to set canonical tags.
  • Added a pointer to the new guidelines from the contributor guide.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4e5ced6a-1a7e-4df6-b50d-88674befd9cf

📥 Commits

Reviewing files that changed from the base of the PR and between 78d0452 and d1d2f89.

📒 Files selected for processing (1)

• CLAUDE.md

✅ Files skipped from review due to trivial changes (1)

• CLAUDE.md

---

📝 Walkthrough

Walkthrough

Adds AGENTS.md, a contributor guide that standardizes documentation by deployment model, defines migrated-section structure (shared source + per-deployment shell files), codifies canonical URL/SEO rules (Network default; OEL self‑hosted exception), and provides a step‑by‑step migration workflow and contributor directives. (≤50 words)

Changes

Cohort / File(s)	Summary
New contributor guide AGENTS.md	Introduces migration detection rules (sidebar route presence or presence in deployment folders), prescribes shared source under /src/components/shared/<product>/... with per-deployment shell files in docs/<deployment>/..., specifies that only shell files are added to sidebars, and documents canonical URL/SEO rules and a step‑by‑step migration workflow.
Reference update CLAUDE.md	Adds a one‑line pointer directing readers to consult AGENTS.md.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped through pages, stitched shared bones to shell,
Canonical banners waving, tidy as a bell,
Sidebars hum in order, deploys know their place,
I leave a trail of carrots — contributors, embrace! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description is minimal but appropriate for a documentation improvement. However, it lacks the structured format specified in the template, including missing sections like 'Related Issue or Design Document' and the checklist.	Consider following the repository's description template more closely by including the 'Related Issue or Design Document' section and completing the checklist items to provide reviewers with clear confirmation of requirements met.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main change: introducing a new AGENTS.md file with contributor guidance on documentation organization and structure.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch hperl/add-agents-md

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Line 41: Update AGENTS.md to use consistent markdown spacing by adding a space
after label colons; specifically change label instances like
"Location:`/src/components/shared/<product>/...`" and any "possible:`...`"
occurrences so they read "Location: `/src/components/shared/<product>/...`" and
"possible: `...`" (also fix the same issue at the other occurrence reported
around line 104); ensure all similar label:value pairs in the file follow the
"Label: value" spacing convention.
- Around line 171-173: Replace the malformed canonical tag example that uses the
invalid token "linkrel" with a correct link element; locate the snippet showing
`<linkrel="canonical" href="..."/>` in AGENTS.md and change it to a proper
`<link rel="canonical" href="..." />` so the canonical link is valid HTML.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 2652a719-7562-4054-9666-01d2e3c96abf

📥 Commits

Reviewing files that changed from the base of the PR and between 0e1a994 and bb5a77f.

📒 Files selected for processing (1)

• AGENTS.md

[Copilot]

Pull request overview

Adds an AGENTS.md guide describing the repo’s transitional docs organization by deployment model (Network / OEL / OSS) and how contributors should structure shared content, shell pages, sidebars, and canonical URLs.

Changes:

• Introduces AGENTS.md with guidance for migrated vs non-migrated docs sections.
• Documents the shared-content vs deployment-shell pattern and sidebar responsibilities.
• Defines canonical URL rules for cross-deployment duplicated content.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[aeneasr]

Can you add CLAUDE.md with contents @AGENTS.md so that claude picks up the agents file? It's the official workaround to get claude to read agents

[vinckr]

do we need to commit this here?
wouldn't it be enough for those that actually work on the docs to have locally/internally?

[hperl]

do we need to commit this here? wouldn't it be enough for those that actually work on the docs to have locally/internally?

I strongly suggest putting this directly into the repo, so that everybody has the same, up-to-date rules all the time. The alternative is clearly worse: every dev needs to add this file to the repo locally, and keep it current with what we have in Notion.

Rather, we should embrace this approach and not just add information about the structure, but also tone of voice, style guides, etc. CONTRIBUTING.md has little content on that.

[vinckr]

do we need to commit this here? wouldn't it be enough for those that actually work on the docs to have locally/internally?

I strongly suggest putting this directly into the repo, so that everybody has the same, up-to-date rules all the time. The alternative is clearly worse: every dev needs to add this file to the repo locally, and keep it current with what we have in Notion.

Rather, we should embrace this approach and not just add information about the structure, but also tone of voice, style guides, etc. CONTRIBUTING.md has little content on that.

the README.md has content on the style that should be followed. Couldn't you give that as context?

The guidenace in the file committed here seems to be only for the ongoing migration and should not be relevant after that is done.

in any case we need to have 1 source of truth for these rules and having multiple files (agents, readme) will make things more confusing not less.

couldn't you point to the README like you did in Claude.md "see README.md" and then add these rules about the migration strategy there?

[hperl]

The guidenace in the file committed here seems to be only for the ongoing migration and should not be relevant after that is done.

There's important information in the doc that is not in the README, which made me want to add it in the first place. Specifically the whole section about the new structure is just documenting the structure, not the migration:

### Shared Source Content

- Location: `/src/components/shared/<product>/...`
- Purpose:
  - Reusable, deployment-agnostic content
  - Written once, used across deployments

### Deployment Shell Files

Locations:

- `docs/network`
- `docs/oel`
- `docs/oss`

Shell files:

- Import content from `/src/components/shared/...`
- Represent a page for a specific deployment
- Are the files added to sidebars

---

## Sidebars

- Each deployment has its **own sidebar**

When adding a page:

- Add the **shell file** (not the shared source file)
- Only include it in deployments where the feature exists

## Canonical URL Rules (SEO)

When the same content exists across multiple deployments, you must define a
canonical URL.

### Default (Most Cases)

**Ory Network is canonical**

- Network → self-canonical
- OEL → canonical points to Network
- OSS → canonical points to Network

### Self-Hosted Exception

If content is specific to **self-hosted (OEL/OSS)**: **OEL is canonical**

- OEL → self-canonical
- OSS → canonical points to OEL
- Network → usually not applicable

in any case we need to have 1 source of truth for these rules and having multiple files (agents, readme) will make things more confusing not less.

couldn't you point to the README like you did in Claude.md "see README.md" and then add these rules about the migration strategy there?

We can also put everything in README, I'm fine with that. I just want all documentation about the documentation structure to live in the repo, to be consumed by humans and agents alike.