Feat/gitlab readme toc placement

CLAUDE.md

@@ -25,6 +25,8 @@ static HTML. The browser never holds a token or calls the GitLab API.
   `moduleResolution: "Bundler"` / ESM setup. Match this in new files.
 - Keep components **pure**: they receive a `data` or `error` prop and render —
   no fetching, no hooks, no side effects.
+- When using a library or external softwre, always check the last version and
+  if the project has not been abandonned
 
 ## Commands
 
@@ -115,3 +117,14 @@ docusaurus build
   fetchers use mocked gitbeaker / fake clients; cache and assets use real temp
   dirs). Do not add MSW.
 - The design spec and implementation plan live in `docs/superpowers/`.
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

README.md

@@ -111,11 +111,26 @@ localized; links resolve back to GitLab.
 |---|---|---|---|
 | `project` | string \| number | — | **Required.** |
 | `ref` | string | default branch | Branch, tag, or commit SHA |
+| `toc` | `"hidden" \| "inline" \| "sidebar"` | _auto_ | Where to render the table of contents |
 
 > **Table of contents:** if the README contains a GitLab `[[_TOC_]]` marker on its
 > own line, it is replaced at build time with a generated table of contents linking
 > to the document's `h2`–`h5` headings (which receive slug `id`s). This also works
-> for markdown embedded via `<GitlabFile>` and for release notes.
+> for markdown embedded via `<GitlabFile>` and for release notes. The `toc` prop
+> overrides this default: `toc="inline"` always renders the inline TOC (even without
+> a marker); `toc="sidebar"` renders the README's headings in the page's native
+> right-hand sidebar instead (merged with the page's own headings) and suppresses
+> the inline TOC; `toc="hidden"` renders no TOC and strips any marker. Omitting `toc`
+> keeps today's marker-driven behavior.
+>
+> ```mdx
+> <GitlabReadme project="group/repo" toc="sidebar" />
+> ```
+>
+> Note: in `sidebar` mode the README is injected as pre-rendered HTML, so
+> Docusaurus' broken-anchor checker can't see its heading anchors — harmless at the
+> default `onBrokenAnchors: "warn"` (build succeeds, links work), but would fail a
+> build configured with `onBrokenAnchors: "throw"`.
 
 <!-- -->