diff --git a/AGENTS.md b/AGENTS.md
index e28d4883b9..d335fddbe7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -126,6 +126,54 @@ Additional common fields:
 - `linkTitle:` — sidebar label (keep under 30 chars)
 - `weight:` — ordering within a section
 
+## Sidebar navigation
+
+The section sidebar is rendered by
+`layouts/_partials/sidebar/sections.html`. It starts at `.FirstSection` and
+recursively walks each section's `.Pages`. Page weight controls the default
+order. Section front matter can group entries with `sidebar.groups`, reverse
+their order with `sidebar.reverse`, override a link with `sidebar.goto`, and
+add a badge with `sidebar.badge`.
+
+The sidebar expands the current page's ancestor sections and marks the current
+page with `aria-current`. When changing the recursive templates, pass all
+navigation state through both `renderChildren` and `renderList`. Keep the page
+filter and the `$hasChildren` calculation aligned so an expand control never
+points to an empty list or disappears for a rendered list.
+
+## Hidden pages
+
+Set `sitemap: false` to hide a page from site-wide discovery. This setting:
+
+- Excludes the page from `sitemap.xml`, `metadata.json`, and `llms-full.txt`
+- Excludes the page body from the site search index
+- Adds a `noindex` robots meta tag
+
+The page is still built and remains available through direct links. This is
+not an access control mechanism.
+
+Hugo does not automatically apply `sitemap: false` from a section page to its
+descendants. To hide an entire subtree, cascade the value from the section's
+`_index.md`:
+
+```yaml
+sitemap: false
+cascade:
+  sitemap: false
+```
+
+## Hidden sections in the sidebar
+
+The sidebar uses `sitemap` as a navigation visibility filter. A hidden page is
+absent from the sidebar outside its active navigation path. The current page
+and its ancestors remain visible so direct links to hidden pages do not produce
+an empty navigation path.
+
+When the active path enters a hidden section, `revealHidden` propagates down
+that branch and renders the whole hidden subtree. This keeps the section's
+navigation available while you are in it. The state must remain scoped to that
+branch so unrelated hidden pages stay hidden.
+
 ## Hugo shortcodes
 
 Shortcodes are defined in `layouts/shortcodes/`. Syntax reference is in