docs: prefix repo paths with site/ in skills and references

Author: notowen333

.agents/references/code-verification.md

@@ -2,18 +2,20 @@
 
 When writing or auditing documentation, verify every code example against the actual SDK source. Plausible-but-wrong code erodes developer trust faster than missing documentation.
 
+The docs site lives under `site/` in this repo. All paths in this guide — including those in skill procedures that reference it — are written relative to the repo root, so they include the `site/` prefix where applicable. Run shell commands like `npm run sdk:clone` from inside `site/` (where `package.json` lives).
+
 Use the first tier available in your environment. Fall back only when the preferred tier is unavailable.
 
 ## Tier 1: Local SDK Clones (preferred)
 
 If you have the local clones populated by `npm run sdk:clone`, read directly from disk — it's faster than network calls and avoids API rate limits:
 
 ```
-.build/sdk-python/src/strands/[path]
-.build/sdk-typescript/strands-ts/src/[path]
+site/.build/sdk-python/src/strands/[path]
+site/.build/sdk-typescript/strands-ts/src/[path]
 ```
 
-If the clones aren't present, run `npm run sdk:clone` from the repo root, or fall back to Tier 2.
+If the clones aren't present, run `npm run sdk:clone` from `site/`, or fall back to Tier 2.
 
 **Key Python modules** (under `src/strands/`):
 - `agent/agent.py` — `Agent` class, constructor signature, `__call__`/`stream_async`

.agents/references/mdx-authoring.md

@@ -79,7 +79,7 @@ async function codeConfigurationOption1() {
 ```
 ````
 
-Only the code between markers is rendered. Paths are relative to `src/content/docs/`.
+Only the code between markers is rendered. Paths inside the `--8<--` directive are relative to `site/src/content/docs/`; you can also write them relative to the repo root with the `site/` prefix.
 
 **When to skip the imports file:** the page renders no TypeScript snippets, *or* every snippet body genuinely has zero external imports. Otherwise, write the imports file — relying on the imports at the top of the body `.ts` is wrong, since those lines live above the `[start:...]` marker and never appear in rendered docs.
 
@@ -174,13 +174,13 @@ Link to generated API docs without fragile relative paths:
 
 ## Line Length
 
-90 characters maximum for files under `src/content/docs/`. Template literal contents in snippet files must also stay under 90 characters. Prettier does not enforce this automatically.
+90 characters maximum for files under `site/src/content/docs/`. Template literal contents in snippet files must also stay under 90 characters. Prettier does not enforce this automatically.
 
 ## Gotchas
 
 - **Snippet dedent**: Leading whitespace is automatically stripped from included snippets. If the snippet reference in markdown is indented, content indents to that level.
 - **Tab indentation**: Content inside `<Tab>` must not have leading blank lines or it may not render correctly.
-- **API docs are symlinked**: `src/content/docs/api/python/_generated` and `typescript/_generated` are symlinks to `.build/api-docs/`. Never edit these directly — they are auto-generated.
+- **API docs are symlinked**: `site/src/content/docs/api/python/_generated` and `typescript/_generated` are symlinks to `site/.build/api-docs/`. Never edit these directly — they are auto-generated.
 - **No `TabItem`**: The auto-imported component is `Tab`, not `TabItem` (even though Starlight's native component is called TabItem).
 - **Code theme**: Uses GitHub Light/Dark themes. Follows Starlight's `[data-theme]` attribute.
 - **Formatting**: No semicolons, single quotes, 2-space indent, trailing commas ES5 style (enforced by Prettier).

.agents/skills/docs-audit/SKILL.md

@@ -18,15 +18,15 @@ Assess an existing documentation page. Produces a structured assessment with spe
 
 ## Inputs
 
-- **Target page**: File path in `src/content/docs/` or published URL
+- **Target page**: File path in `site/src/content/docs/` or published URL
 - **Content type**: If known. If not, classify it first.
 - **Context** (optional): Community signals, GitHub issues, or specific concerns
 
 ## Process
 
 ### Step 1: Fetch and classify
 
-Read the source file from `src/content/docs/` in this repo. If you need the published version and have web access, fetch from strandsagents.com.
+Read the source file from `site/src/content/docs/` in this repo. If you need the published version and have web access, fetch from strandsagents.com.
 
 Classify the content type (tutorial, howto, reference, explanation, mixed). Note: "mixed" is itself a finding. Pages that mix types are the most common structural problem.
 

.agents/skills/docs-planner/SKILL.md

@@ -17,7 +17,7 @@ Identify gaps in the docs site and produce a prioritized backlog.
 
 ### Step 1: Inventory current docs
 
-Read `src/config/navigation.yml` for the full navigation tree — this is the authoritative navigation source for the Astro site, loaded by `astro.config.mjs` via `src/sidebar.ts`. The legacy `mkdocs.yml` is no longer wired into the build; ignore it for navigation purposes. Glob `src/content/docs/**/*.{md,mdx}` for all content files. Classify each by content type (tutorial, how-to, reference, explanation, mixed), coverage area (quickstart, tools, agents, multi-agent, deployment, etc.), and estimated freshness (check lastReviewed frontmatter if available, otherwise flag as unknown).
+Read `site/src/config/navigation.yml` for the full navigation tree — this is the authoritative navigation source for the Astro site, loaded by `site/astro.config.mjs` via `site/src/sidebar.ts`. Glob `site/src/content/docs/**/*.{md,mdx}` for all content files. Classify each by content type (tutorial, how-to, reference, explanation, mixed), coverage area (quickstart, tools, agents, multi-agent, deployment, etc.), and estimated freshness (check lastReviewed frontmatter if available, otherwise flag as unknown).
 
 ### Step 2: Identify gaps