refactor: use README.md for folder landing pages

github.com auto-renders a folder's README.md when browsing into it, but not
index.md — so with the content-first layout the harness and locale folders
showed a bare file list instead of their landing page. Rename every folder
landing from index.md to README.md and add an explicit slug: to each so
Starlight keeps routing it to the same URL (the site already used this
mechanism for the root docs/README.md via slug: index).

- docs/<harness>/README.md → slug: <harness>
- docs/<locale>/README.md → slug: <locale>
- docs/<locale>/<harness>/README.md → slug: <locale>/<harness>

Update the authoring docs, copilot-instructions, astro instructions, and the
localizations skill to document the README-landing + slug convention
(including that localized landings must use locale-prefixed slugs).

Build verified: 217 workshop pages, routes preserved, translations render.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 64357866-3a3f-4fd8-914b-77826de5be5a

Author: GeekTrainer

.github/copilot-instructions.md

@@ -8,7 +8,7 @@ This repo hosts the **workshop content** for *Agents in SDLC*, published as an A
 
 - `docs/` — **Source Markdown for all lessons. Edit here.** Browsable directly on github.com; no build required.
   - `README.md` — Workshop landing page (also the site home via `slug: index` frontmatter).
-  - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / Cloud agent / GitHub Copilot app). Each harness opens with its own `0-prerequisites.md` setup lesson; the CLI and VS Code harnesses set up a codespace, while the app and cloud harnesses cover the setup their flow needs (for the app, installing Node.js locally and creating the project from the template).
+  - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / Cloud agent / GitHub Copilot app). Each folder's landing page is a `README.md` (routed via a `slug:` matching the folder path). Each harness opens with its own `0-prerequisites.md` setup lesson; the CLI and VS Code harnesses set up a codespace, while the app and cloud harnesses cover the setup their flow needs (for the app, installing Node.js locally and creating the project from the template).
   - `es-es/`, `ja-jp/`, `ko-kr/`, `pt-br/`, `zh-cn/` — Localized content at the locale-root paths required by Starlight. Translated pages mirror the English path beneath each locale directory; untranslated pages use Starlight's English fallback.
   - `_images/` — Screenshots and diagrams (shared across all locales).
 - `website/` — Optional Astro + Starlight site that publishes `docs/` to GitHub Pages (loader `base: '../docs'`). Only needed to self-host or preview the rendered site.

.github/instructions/astro.instructions.md

@@ -12,7 +12,7 @@ applyTo: 'website/**/*.{astro,mjs,ts,js}'
 - Base path: `/agents-in-sdlc` (the repo's GitHub Pages slug).
 - Site URL: `https://github-samples.github.io/agents-in-sdlc/`.
 - **Sidebar: manually maintained** in `astro.config.mjs`. The `sidebar` array drives both the order learners see and which pages appear in navigation. New lessons must be added explicitly.
-- **Content collection** is sourced from the repo-root `docs/` directory via the custom `glob()` loader in `src/content.config.ts` (`base: '../docs'`). That loader excludes underscore-prefixed files and directories so support assets such as `_images/` don't get routed as pages. The home page (`/`) comes from `docs/README.md` (its `slug: index` frontmatter maps it to the site root).
+- **Content collection** is sourced from the repo-root `docs/` directory via the custom `glob()` loader in `src/content.config.ts` (`base: '../docs'`). That loader excludes underscore-prefixed files and directories so support assets such as `_images/` don't get routed as pages. Folder landing pages are `README.md` files (so they render on github.com) rather than Starlight's default `index.md`; each carries a `slug:` in its frontmatter to reproduce the route it would otherwise get from an index file — `docs/README.md` → `slug: index` (site home `/`), `docs/<harness>/README.md` → `slug: <harness>`, and localized landings use the locale-prefixed slug (`docs/<locale>/README.md` → `slug: <locale>`, `docs/<locale>/<harness>/README.md` → `slug: <locale>/<harness>`).
 
 ## Don't add app-style components
 

.github/skills/localizations/SKILL.md

@@ -18,11 +18,13 @@ The skill takes input content and a list of target locales. It then translates t
 └── docs/                         ← workshop content (source + locale outputs)
     ├── README.md                 ← landing page (source; slug: index)
     ├── <harness>/                ← English lessons (source)
+    │   ├── README.md             ← harness landing (source; slug: <harness>)
     │   └── *.md
     ├── _images/                  ← shared assets (not localized)
     └── <locale>/                 ← localized output, direct child of docs/
-        ├── index.md
-        └── <any/path>/
+        ├── README.md             ← locale landing (slug: <locale>)
+        └── <harness>/
+            ├── README.md         ← localized harness landing (slug: <locale>/<harness>)
             └── *.md
 ```
 
@@ -64,7 +66,7 @@ The process runs in two passes. First, the content is analyzed to identify key p
 
 Regardless of locale, the following must be preserved exactly and **not** translated:
 
-- YAML frontmatter **keys** (translate values only where appropriate, e.g. a `title`).
+- YAML frontmatter **keys** (translate values only where appropriate, e.g. a `title`). **Exception — the `slug` key on landing pages (`README.md`):** the site routes each folder landing via its `slug`, so a localized landing must carry a **locale-prefixed** slug rather than the English one. Rewrite it: a locale root (`docs/<locale>/README.md`) uses `slug: <locale>`, and a localized harness landing (`docs/<locale>/<harness>/README.md`) uses `slug: <locale>/<harness>`. Never copy the English `slug: index` / `slug: <harness>` verbatim into a localized file — that would collide with the English route.
 - Fenced and inline code, including variable, function, and command names.
 - URLs and external link targets.
 - HTML tags, Markdown structure, tables, and admonition markers.

AUTHORING.md

@@ -62,6 +62,17 @@ agents-in-sdlc/
 5. **Register in the sidebar.** Open `website/astro.config.mjs` and add an entry to the appropriate `items: []` block. The sidebar is *manually* maintained — order in the file is the order learners see.
 6. **Preview and verify, then open a PR.** Preview locally and run the verification sequence before committing — see [Building and verifying](#building-and-verifying) below. CI runs the Astro build and the lychee link check; both must pass.
 
+### Landing pages (folder `README.md`)
+
+Every folder's landing page is a `README.md` so it renders directly when someone browses that folder on github.com. Because Starlight normally derives a folder's index route from an `index.md`, each landing carries an explicit `slug:` in its frontmatter that reproduces the route:
+
+- `docs/README.md` → `slug: index` (site home `/`).
+- `docs/<harness>/README.md` → `slug: <harness>` (e.g. `slug: app` → `/app/`).
+- `docs/<locale>/README.md` → `slug: <locale>` (e.g. `slug: es-es` → `/es-es/`).
+- `docs/<locale>/<harness>/README.md` → `slug: <locale>/<harness>` (e.g. `slug: es-es/app` → `/es-es/app/`).
+
+When you add a new harness or locale landing, name it `README.md` and set its `slug:` to match the folder path. Localized landings must use the locale-prefixed slug, never the English one.
+
 ### Add an image
 
 1. **Drop the file** in `docs/_images/` (or a path-scoped `cli/_images/` etc. when the image is path-specific). Use lowercase-with-hyphens filenames; prefix with `shared-` if the image is referenced from multiple harnesses.

README.md

@@ -21,7 +21,7 @@ For PR/CI rules, see **[CONTRIBUTING.md](./CONTRIBUTING.md)**.
 
 - **`docs/`** — **Lesson source (plain Markdown). Edit here.** Browsable directly on github.com, no build required.
   - `README.md` — Workshop landing page (also the published site's home via `slug: index`).
-  - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / cloud agent / GitHub Copilot app). Each codespace-based harness opens with its own `0-prerequisites.md` setup lesson.
+  - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / cloud agent / GitHub Copilot app). Each codespace-based harness opens with its own `0-prerequisites.md` setup lesson, and a folder `README.md` (routed via a `slug:` matching the folder) is its landing page.
   - `es-es/`, `ja-jp/`, `ko-kr/`, `pt-br/`, `zh-cn/` — Translated locale trees (currently the app harness).
   - `_images/` — Screenshots and diagrams (shared across all locales).
 - **`website/`** — Optional Astro + Starlight site that publishes `docs/` to GitHub Pages. Only needed to self-host or preview the rendered site.

docs/app/index.md docs/app/README.mddocs/app/index.md renamed to docs/app/README.md

@@ -1,4 +1,5 @@
 ---
+slug: app
 title: "GitHub Copilot app"
 authors:
   - geektrainer

docs/cli/index.md docs/cli/README.mddocs/cli/index.md renamed to docs/cli/README.md

@@ -1,4 +1,5 @@
 ---
+slug: cli
 title: "GitHub Copilot CLI"
 authors:
   - geektrainer

docs/cloud/index.md docs/cloud/README.mddocs/cloud/index.md renamed to docs/cloud/README.md

@@ -1,4 +1,5 @@
 ---
+slug: cloud
 title: "Copilot cloud agent"
 authors:
   - geektrainer

docs/es-es/index.md docs/es-es/README.mddocs/es-es/index.md renamed to docs/es-es/README.md

@@ -1,4 +1,5 @@
 ---
+slug: es-es
 title: "Agentes en el ciclo de vida del desarrollo de software (SDLC)"
 authors:
   - geektrainer

docs/es-es/app/index.md docs/es-es/app/README.mddocs/es-es/app/index.md renamed to docs/es-es/app/README.md

@@ -1,4 +1,5 @@
 ---
+slug: es-es/app
 title: "Aplicación GitHub Copilot"
 authors:
   - geektrainer