docs: add dedicated context/decisions pages, reframe decisions around rejected alternatives

[gregology]

What this changes

Context entries and decisions are the two core concepts of the product, but neither had its own page. Their docs were split across protocol.md (a spec aimed at implementors) and examples.md (a cookbook). If you wanted to understand decisions, you'd read part of the protocol spec for the schema, scroll through examples for the patterns, and mentally stitch them together.

Now they each get a dedicated page. The nav goes from:

Home -> Getting started -> Protocol -> Examples -> ...

to:

Home -> Getting started -> Context entries -> Decisions -> Examples -> Protocol -> ...

Why: the "nos" framing for decisions

The bigger motivation here is a reframe of what decisions are for.

The old docs framed decisions as "capture what you chose and why." That's fine, but the code already shows what you chose. If you picked Postgres, the agent can see psycopg2 in requirements and SQL migrations on disk. A YAML entry restating that adds almost nothing.

What the code can't show is what you rejected. You evaluated DynamoDB and walked away because of single-table design complexity? That's invisible. It lives in people's heads and old Slack threads.

Decisions should primarily capture the "nos": the rejected alternatives, the specific constraints behind each rejection, and the conditions under which those constraints might change. This is the most valuable information for agents because the most expensive agent mistake is confidently proposing a migration to something you already evaluated and ruled out. That wastes review cycles and reopens settled debates.

The alternatives, reason_rejected, and revisit_when fields already existed in the schema. The docs just didn't frame them as the primary reason decisions exist. Now they do.

Alternatives considered for the restructure

Keep the current two-page split (protocol + examples), just update the framing. We tried this first. It worked for the reframe itself, but the decisions content ended up scattered: schema in protocol.md, the "nos" explanation in protocol.md, writing guidance in examples.md. A user learning about decisions would bounce between two pages. The framing change made the structural problem more obvious, not less.

Merge everything into protocol.md. Would make protocol.md huge and contradicts its stated purpose ("written for implementors building tools"). Most people writing AGENTS.yaml files aren't building tools. They shouldn't have to read a resolution algorithm spec to learn how match patterns work.

Create concept pages but remove the examples page. The examples page shows complete AGENTS.yaml files with context and decisions working together in real project setups (dbt, API, React, Terraform, monorepo). Splitting those examples across two concept pages would lose the "full picture" quality. The examples page earns its existence by showing complete files organized by project type.

Create a single "Writing AGENTS.yaml" page covering both concepts. This was tempting. But decisions need room. The "nos" framing, the weak-vs-strong comparison, the revisit_when explanation of constraint expiration. Cramming that into a shared page with context entry docs would bury it. The whole point of this change is that decisions deserve more prominence, not less.

We landed on: two concept pages, examples stays as the cookbook, protocol slims down to the implementor-facing spec (file discovery, resolution algorithm, merge order, validation rules).

[gregology]

Restructures docs by pulling context entries and decisions into their own dedicated pages, reframing decisions around rejected alternatives (the "nos"), and slimming protocol.md down to an implementor-focused spec. The nav and cross-links are updated throughout. Good motivation — the old split across protocol + examples made decisions hard to learn.

Critical: leaked sctx hook output in four doc pages

All four doc files in this PR end with a ## Structured Context section containing Go project bullet points pulled verbatim from the root AGENTS.yaml (lines 10, 18, 39). This is agent-injected context that got committed as page content. It'll render on the live site as a visible section that has nothing to do with the page topic.

docs/context.md lines 154-158:

## Structured Context

- This is a Go project. Follow idiomatic Go conventions...
- The core engine (internal/core) must have zero knowledge...
- Both AGENTS.yaml and AGENTS.yml are recognized...

Same thing in:

• docs/decisions.md lines 122-127
• docs/examples.md lines 314-317
• docs/protocol.md lines 108-112

The protocol.md one is especially bad because it looks like it could be part of the spec.

Fix: Delete the ## Structured Context section from all four files.

Warning: README asymmetry between context entries and decisions

The Decisions subsection in README.md (line 79) got the full "nos" reframe with an expanded YAML example showing alternatives. But the Context entries subsection (lines 68-77) was left untouched — no link to the new context.md page, no updated framing. Given that index.md now positions these as the two co-equal "building blocks," the README tells a lopsided story.

Fix: Even just a closing line like See [sctx.dev/context](https://sctx.dev/context/) for detailed field documentation. would balance it out.

Note: protocol.md summary tables lost their Description column

The summary tables for context entry fields (lines 56-64) and decision entry fields (lines 68-75) now show field name, type, required, and default — but no description. The old protocol.md had descriptions inline. Implementors building tools against this spec now have to click through to concept pages to learn what on or when actually mean.

Fix: Add a short Description column back. Even terse labels like "Action filter" and "Prompt positioning" would keep the spec self-contained for its audience.

---

The restructure and the "nos" reframing are well done. The leaked ## Structured Context sections are the blocker — those need to go before merge.

Developer metrics

Total duration: 2m 34s
Turns: 42
Tool calls: 34
Tokens: 552,090 input / 4,991 output

Stage	Model	Duration	Turns	Tool calls	Tokens (in/out)	Cache read	Cache creation
analyze	claude-opus-4-6	1m 24s	37	31	279,356 / 2,469	236,857	42,483
review_findings	claude-opus-4-6	0m 47s	4	2	159,570 / 1,817	110,926	48,638
draft	claude-opus-4-6	0m 22s	1	1	113,164 / 705	62,505	50,656

[gregology]

Restructures docs so context entries and decisions each get their own page, reframes decisions around capturing rejected alternatives ("the nos") rather than restating what the code already shows, and slims protocol.md down to the implementor-facing spec.

Good restructure. The "nos" framing is a real improvement — it's the right way to think about what decisions are for. A few things I noticed:

Warnings

README.md line 99 — missing link to decisions page

The context entries section links out to sctx.dev/context (line 79) but the decisions section right below it has no equivalent link to sctx.dev/decisions. Kind of ironic given the whole PR is about giving decisions more prominence. Add something like:

See [sctx.dev/decisions](https://sctx.dev/decisions/) for the full "nos" framing and field documentation.

README.md line 89 — README and decisions.md examples will drift

The REST-over-GraphQL YAML example appears in both README and docs/decisions.md but with different reason_rejected strings. README has "No team experience, complex caching", decisions.md has "Team has no GraphQL experience, caching is complex". Close enough to look like they should match, different enough to be confusing. Either sync them or use a different example in the README so there's no expectation of parity.

Notes

docs/getting-started.md line 187 — protocol spec link dropped from "What's next"

The old version linked to the protocol spec here. Now it's gone. Someone arriving from getting-started who's building a tool (not writing AGENTS.yaml) loses the direct path. Maybe add it back as a last bullet:

- [Protocol spec](protocol.md) -- file format and resolution algorithm for tool implementors

docs/protocol.md line 54 — "full schema" oversells what the linked pages are

The text says "See Context entries for the full context entry schema" but those pages are conceptual guides with writing advice, not schema references. Something like "field details and writing guidance" would be more accurate.

---

Nothing blocking here. The two warnings are worth a quick fix before merge.

Developer metrics

Total duration: 2m 7s
Turns: 29
Tool calls: 23
Tokens: 532,484 input / 4,638 output

Stage	Model	Duration	Turns	Tool calls	Tokens (in/out)	Cache read	Cache creation
analyze	claude-opus-4-6	0m 59s	18	15	221,871 / 2,108	188,683	33,176
review_findings	claude-opus-4-6	0m 50s	10	7	217,547 / 1,957	181,276	36,263
draft	claude-opus-4-6	0m 17s	1	1	93,066 / 573	54,877	38,186

[gregology]

Adds dedicated concept pages for context entries and decisions, restructures the nav to feature them, and reframes decisions around capturing rejected alternatives ("the nos") rather than restating what the code already shows. Docs-only, no code changes.

Overall this is a well-motivated restructure — the "nos" framing is a genuinely better way to think about decisions, and giving each concept its own page makes the docs easier to navigate. A few things worth looking at:

---

⚠️ protocol.md lost the alternatives sub-field schema

The detailed alternatives sub-field definition (option and reason_rejected, both required strings) got removed when protocol.md was slimmed down. The summary table just says alternatives | list | ... | Rejected options and constraints with no definition of what each list item looks like. An implementor building a parser needs that structure, and the cross-link points to decisions.md which is written as user-facing guidance, not a spec.

The resolution algorithm kept its implementor-level precision — the decision schema should too. One line under the summary table would fix it:

Each alternatives entry has two required fields: option (string, the alternative considered) and reason_rejected (string, the constraint that ruled it out).

---

Minor notes

README asymmetry — The Decisions section got expanded with an alternatives example block and a link to sctx.dev/decisions, but the Context section only got a brief "See sctx.dev/context" link. The context field summary in the README also doesn't mention exclude, so only three of the four filter fields are listed. Not a big deal, but adding exclude to the bullet list would keep things balanced.

docs/context.md line 62 — gitignore comparison — The match/exclude section says glob syntax is "Same syntax as .gitignore and .editorconfig" but .gitignore supports negation patterns (!pattern) which sctx doesn't — sctx uses exclude instead. Could trip someone up. Something like "Standard glob patterns (*, **, ?). Similar to .gitignore but negation patterns aren't supported — use the exclude field instead" would be more precise.

REST/GraphQL example in three places — The same YAML block now appears in README.md, decisions.md, and protocol.md. If the schema changes later, that's three places to update. Worth keeping in mind, no action needed right now.

---

Looks good to me. The protocol.md sub-field thing is the only one I'd want addressed before merge — the rest are suggestions you can take or leave.

Developer metrics

Total duration: 3m 24s
Turns: 34
Tool calls: 29
Tokens: 385,729 input / 5,690 output

Stage	Model	Duration	Turns	Tool calls	Tokens (in/out)	Cache read	Cache creation
analyze	claude-opus-4-6	1m 52s	30	26	146,530 / 2,591	111,382	35,139
review_findings	claude-opus-4-6	1m 4s	3	2	139,246 / 2,433	99,725	39,515
draft	claude-opus-4-6	0m 27s	1	1	99,953 / 666	58,274	41,676