Better docs retrieval

AGENTS-drupal.md

@@ -4,19 +4,19 @@
 - Drupal 10/11
 - Local development via DDEV
 - PHP 8.3+
-- Custom theme `gesso` (see [agent_docs/gesso_drupal.md](agent_docs/gesso_drupal.md))
+- Custom theme `gesso` (see [agent_docs/gesso_drupal.md](agent_docs/drupal/front-end/overview.md))
 <!-- TODO: Add project-specific details (e.g., "Multilingual site (English/Spanish)", "Headless CMS with Next.js frontend") -->
 
 ## Critical Rules
 
 ### Theme — Gesso
 **IMPORTANT**: Before any work in the Gesso theme, you **MUST** read
-[agent_docs/gesso_drupal.md](agent_docs/gesso_drupal.md).
+[agent_docs/gesso_drupal.md](agent_docs/drupal/front-end/overview.md).
 
 ### Contrib & Core — Do Not Modify
 **NEVER edit files in `web/core/` or `web/modules/contrib/`.**
 These are managed by Composer and will be overwritten.
-See [agent_docs/drupal_patching.md](agent_docs/drupal_patching.md) for the patch workflow.
+See [agent_docs/drupal_patching.md](agent_docs/drupal/back-end/drupal_patching.md) for the patch workflow.
 
 ## Essential Commands
 
@@ -28,7 +28,7 @@ ddev drush config:import -y             # Import config after git pull
 ddev drush uli                          # Admin login link
 ```
 
-Full command reference: [agent_docs/drupal_commands.md](agent_docs/drupal_commands.md)
+Full command reference: [agent_docs/drupal_commands.md](agent_docs/drupal/back-end/drupal_commands.md)
 
 ## File Locations
 
@@ -39,54 +39,3 @@ Full command reference: [agent_docs/drupal_commands.md](agent_docs/drupal_comman
 | Config sync | `config/sync/` |
 | Contrib modules | `web/modules/contrib/` (do not edit) |
 | Core | `web/core/` (do not edit) |
-
-## Reference Documentation
-
-**Read the relevant doc BEFORE starting work in that area.**
-
-| Topic | Document | Read before... |
-|-------|----------|----------------|
-| **Commands** | [agent_docs/drupal_commands.md](agent_docs/drupal_commands.md) | Running drush or ddev commands |
-| **Code Style** | [agent_docs/drupal_code_style.md](agent_docs/drupal_code_style.md) | Writing PHP code |
-| **Configuration** | [agent_docs/drupal_config.md](agent_docs/drupal_config.md) | Exporting/importing config |
-| **Custom Modules** | [agent_docs/drupal_custom_modules.md](agent_docs/drupal_custom_modules.md) | Creating or modifying modules |
-| **Patching** | [agent_docs/drupal_patching.md](agent_docs/drupal_patching.md) | Fixing bugs in contrib/core |
-| **Troubleshooting** | [agent_docs/drupal_troubleshooting.md](agent_docs/drupal_troubleshooting.md) | Debugging errors |
-| **Testing** | [agent_docs/drupal_testing.md](agent_docs/drupal_testing.md) | Running phpcs, phpstan, phpunit |
-
-### Theme Documentation (Gesso)
-
-| Topic | Document | Read before... |
-|-------|----------|----------------|
-| **Gesso Overview** | [agent_docs/gesso_drupal.md](agent_docs/gesso_drupal.md) | Any theme work |
-| **Sass** | [agent_docs/sass_conventions.md](agent_docs/sass_conventions.md) | Writing SCSS files |
-| **JavaScript** | [agent_docs/drupal_js_conventions.md](agent_docs/drupal_js_conventions.md) | Writing JS in theme |
-| **Storybook** | [agent_docs/storybook_drupal.md](agent_docs/storybook_drupal.md) | Creating stories |
-| **Design Tokens** | [agent_docs/design_tokens.md](agent_docs/design_tokens.md) | Working with colors, spacing, typography |
-| **Twig** | [agent_docs/drupal_twig.md](agent_docs/drupal_twig.md) | Working with Twig or template fields |
-
-<!--
-## Architectural Patterns
-
-### Search API
-- **Server**: [e.g., ddev_solr (Solr 8.x)]
-- **Indexes**:
-  - `content` — Main content search
-  - `[index_name]` — [description]
-- **Reindex**: `ddev drush search-api:reset-tracker [index] && ddev drush search-api:index [index]`
--->
-
-<!--
-## Multilingual Support
-- Languages: [e.g., English, Spanish]
-- Translation updates: `ddev drush locale:check && ddev drush locale:update`
--->
-
-<!--
-## Project Documentation
-
-| Topic | Document | Read before... |
-|-------|----------|----------------|
-| Groups | `agent_docs/groups.md` | Working with groups or memberships |
-| Notifications | `agent_docs/notifications.md` | Working with email notifications |
--->

AGENTS-nextjs.md

@@ -64,15 +64,3 @@ npm run build-icons               # Generate React components from SVGs in sourc
 - `lib/` - Build scripts and custom PostCSS plugins
 - `util/` - Runtime utility functions
 - `starterkits/` - CMS-specific starter code (Drupal, WordPress)
-
-## Reference Material
-**IMPORTANT**: When working on features related to the topics below, ALWAYS read
-the corresponding documentation in agent_docs/ for detailed context, implementation
-patterns, and best practices.
-
-| Topic              | Document                                                                         | Read before...                 |
-|--------------------|----------------------------------------------------------------------------------|--------------------------------|
-| **React**          | [agent_docs/react_component_conventions.md](agent_docs/sass_conventions.md)      | Working with React components  |
-| **CSS**            | [agent_docs/css_conventions_conventions.md](agent_docs/drupal_js_conventions.md) | Writing CSS                    |
-| **Storybook**      | [agent_docs/storybook_nextjs.md](agent_docs/storybook_drupal.md)                 | Creating stories               |
-| **Twig**           | [agent_docs/drupal_twig.md](agent_docs/drupal_twig.md)                           | Setting up a headless CMS Site |

README.md

@@ -5,7 +5,7 @@ Starter kit for generative AI skills for tools like Claude Code and Cursor
 * [Node.js](https://nodejs.org/en/)
 * `tiged` installed: `npm install -g tiged`
 
-## Usage
+## Set Up
 Find the type of project you have below and follow the instructions.
 
 ## Drupal usage
@@ -15,7 +15,7 @@ Find the type of project you have below and follow the instructions.
    ```
 2. Download the `agent_docs` directory to the root level of your repo:
    ```bash
-   degit forumone/f1-genai-starter/agent_docs agent_docs
+   curl -fsSL https://raw.githubusercontent.com/forumone/f1-genai-starter/main/download-agent-docs.sh | bash drupal
    ```
 3. If your site is not using **Gesso 5** as your theme, remove the Gesso theme section from the file.
 
@@ -26,9 +26,17 @@ Find the type of project you have below and follow the instructions.
    ```
 2. Download the `agent_docs` directory to the root level of your repo:
    ```bash
-   degit forumone/f1-genai-starter/agent_docs agent_docs
+   curl -fsSL https://raw.githubusercontent.com/forumone/f1-genai-starter/main/download-agent-docs.sh | bash nextjs
    ```
 
+## Usage
+1. Add a `project` directory within `agent_docs`. All project-specific documentation should go there. You can create subfolders within `project` as well.
+2. Run the update script from the root of your repo whenever you add or remove a documentation file:
+   ```bash
+   bash agent_docs/shared/update-toc.sh
+   ``` 
+3. To update the base documentation, re-run the download script.
+
 ## Adding Skills and Subagents
 
 ### Claude Code
@@ -53,9 +61,9 @@ one way, try anohter.
 3. Copy any skills or agents you want to use from this repo to the appropriate directory. Note that for skills, you need to copy the entire directory with the `SKILLS.md` file, not just the Markdown file.
 
 ### Available Skills
-- `create-component` (Next.js only) - Creates a new component. (See `Prerequistes` in the skill definition for what you should provide in the prompt). **Requires updated component.js script from nextjs-project**
+- `create-component` (Next.js only) - Creates a new component. (See `Prerequisites` in the skill definition for what you should provide in the prompt). **Requires updated component.js script from nextjs-project**
 - `npm-package-updates` (Any Gesso) - Updates npm packages
-- `upgrade-gesso` (Gesso 5 for Drupal only) - Upgrades a theme to the next Gesso release. **Requires the GitHub CLI to be installed and the GitHub MCP server configured.**
+- `upgrade-gesso` (Gesso 5 for Drupal only) - Upgrades a theme to the next Gesso release.
    - `plan-gesso-upgrade` - Skill used by `upgrade-gesso`
    - `implement-gesso-upgrade` - Skill used by `upgrade-gesso`
 ### Available Agents

agent_docs/drupal_code_style.md → agent_docs/drupal/back-end/drupal_code_style.md

@@ -1,4 +1,7 @@
-# Drupal Code Style Guidelines
+---
+title: Drupal Code Style
+description: Read when writing PHP code
+---
 
 ## General Rules
 

agent_docs/drupal_commands.md → agent_docs/drupal/back-end/drupal_commands.md

@@ -1,6 +1,7 @@
-# Drupal Commands Reference
-
-Quick reference for common drush and ddev commands.
+---
+title: Drupal Commands Reference
+description: Read when running ddev or drush commands
+---
 
 ## DDEV Environment
 

agent_docs/drupal_config.md → agent_docs/drupal/back-end/drupal_config.md

@@ -1,4 +1,7 @@
-# Drupal Configuration Management
+---
+title: Drupal Configuration Management
+description: Read when exporting/importing config
+---
 
 ## Key Concepts
 

agent_docs/drupal_custom_modules.md → agent_docs/drupal/back-end/drupal_custom_modules.md

@@ -1,4 +1,7 @@
-# Drupal Custom Modules
+---
+title: Drupal custom modules
+description: Read when creating or modifying modules
+---
 
 ## File Structure
 

agent_docs/drupal_patching.md → agent_docs/drupal/back-end/drupal_patching.md

@@ -1,4 +1,7 @@
-# Patching Contrib & Core Modules
+---
+title: Patching Contrib & Core Modules
+description: Read when fixing bugs in contrib/core
+---
 
 ## Critical Rule
 

agent_docs/drupal_testing.md → agent_docs/drupal/back-end/drupal_testing.md

@@ -1,4 +1,7 @@
-# Drupal Testing & Code Quality
+---
+title: Drupal Testing & Code Quality
+description: Read when running phpcs, phpstan, phpunit
+---
 
 ## Quick Reference
 

agent_docs/drupal_troubleshooting.md → agent_docs/drupal/back-end/drupal_troubleshooting.md

@@ -1,4 +1,7 @@
-# Drupal Troubleshooting
+---
+title: Drupal Troubleshooting
+description: Read when debugging errors
+---
 
 ## Debugging Workflow
 

agent_docs/design_tokens.md → agent_docs/drupal/front-end/design_tokens.md

@@ -1,4 +1,7 @@
-# Design Tokens
+---
+title: Design Tokens
+description: Read when working with colors, spacing, typography
+---
 
 ## Source of Truth
 

agent_docs/drupal_js_conventions.md → agent_docs/drupal/front-end/drupal_js_conventions.md

@@ -1,4 +1,7 @@
-# JavaScript Conventions
+---
+title: JavaScript Conventions
+description: Read when writing JavaScript or TypeScript
+---
 
 Prefer JavaScript unless editing a TypeScript file or TypeScript is specified.
 
@@ -65,7 +68,7 @@ Drupal.behaviors.dropdownMenu = {
 import { TRANSITIONS, BREAKPOINTS, COLORS } from '../../00-config/_GESSO.es6';
 ```
 
-See `/agent_docs/design-tokens.md` for token structure and available exports.
+See [design-tokens.md](design_tokens.md) for token structure and available exports.
 
 ## Available Utilities
 Location: `source/06-utility`

agent_docs/drupal_react_conventions.md → agent_docs/drupal/front-end/drupal_react_conventions.md

@@ -1,4 +1,7 @@
-# React Components in Drupal
+---
+title: React Components in Drupal
+description: Read when writing a React component within a Drupal theme.
+---
 
 ## Directory
 

agent_docs/drupal_twig.md → agent_docs/drupal/front-end/drupal_twig.md

@@ -1,4 +1,7 @@
-# Drupal Twig Templates
+---
+title: Drupal Twig Templates
+description: Read when working with Twig or Drupal templates
+---
 This document covers Twig patterns **unique to the Gesso theme**. Standard Drupal Twig knowledge is assumed.
 
 ## Two-Layer Template Architecture

agent_docs/gesso_drupal.md → agent_docs/drupal/front-end/overview.md

@@ -1,4 +1,7 @@
-# Gesso Drupal Theme
+---
+title: Overview
+description: Read when doing any theme work
+---
 
 ## Project Overview
 - Drupal 10/11 theme
@@ -38,17 +41,3 @@ Configured in `gesso.info.yml` and `.storybook/main.js`:
 - `@layouts` → `source/02-layouts`
 - `@components` → `source/03-components`
 - `@templates` → `source/04-templates`
-
-## Reference Material
-**IMPORTANT**: When working on features related to the topics below, ALWAYS read
-the corresponding documentation in agent_docs/ for detailed context, implementation
-patterns, and best practices.
-
-| Topic | Document | Read before... |
-|-------|----------|----------------|
-| **Gesso Overview** | [agent_docs/gesso_drupal.md](agent_docs/gesso_drupal.md) | Any theme work |
-| **Sass** | [agent_docs/sass_conventions.md](agent_docs/sass_conventions.md) | Writing SCSS files |
-| **JavaScript** | [agent_docs/drupal_js_conventions.md](agent_docs/drupal_js_conventions.md) | Writing JS in theme |
-| **Storybook** | [agent_docs/storybook_drupal.md](agent_docs/storybook_drupal.md) | Creating stories |
-| **Design Tokens** | [agent_docs/design_tokens.md](agent_docs/design_tokens.md) | Working with colors, spacing, typography |
-| **Twig** | [agent_docs/drupal_twig.md](agent_docs/drupal_twig.md) | Working with Twig or template fields |

agent_docs/sass_conventions.md → agent_docs/drupal/front-end/sass_conventions.md

@@ -1,4 +1,10 @@
-# Sass Conventions
+---
+title: Sass Conventions
+description: Read when writing SCSS files
+---
+## CSS Rules
+Read [../shared/front-end/css_rules.md](../shared/front-end/css_rules.md) for CSS
+rules that should be followed across all projects.
 
 ## CSS Class Conventions
 
@@ -54,7 +60,3 @@ Location: `source/00-config/mixins/_breakpoint.scss`
 
 Prefer breakpoint mixins to hard-coding media queries. Prefer using min-width
 queries (mobile first) over max-width queries.
-
-## Logical Properties
-
-Always use CSS logical properties instead of physical directions.

agent_docs/storybook_drupal.md → agent_docs/drupal/front-end/storybook_drupal.md

@@ -1,4 +1,7 @@
-# Storybook Conventions
+---
+title: Storybook Conventions
+description: Read when creating or editing stories
+---
 
 ## Story File Structure
 
@@ -71,8 +74,9 @@ decorators: [withGlobalWrapper],
 
 ## Story Variations
 
-Use CSF 3 and reuse stories with the spread operator. See https://storybook.js.org/docs/api/csf/index#spreadable-story-objects
-for documentation.
+See [shared Storybook guidelines](../shared/front-end/storybook.md) for the general pattern.
+
+In Drupal stories, variants also carry a `render` function:
 
 ```javascript
 const Primary = {

agent_docs/css_conventions.md → agent_docs/nextjs/css_conventions.md

@@ -1,6 +1,10 @@
-# CSS Conventions
-
-This file provides information about the CSS architecture and usage.
+---
+title: CSS Conventions
+description: Information about CSS architecture and usage specific to Next.js projects
+---
+## CSS Rules
+Read [../shared/front-end/css_rules.md](../shared/front-end/css_rules.md) for CSS
+rules that should be followed across all projects.
 
 ## CSS Architecture
 
@@ -29,19 +33,13 @@ updating components.
 `postcss-advanced-variables` allows for Sass-like mixins. Mixins are located in `source/00-config/mixins/`.
 Project configuration allows shorthand imports: `@import "mixins";` resolves to `/source/00-config/mixins.css`.
 
-### Linting
-**IMPORTANT**: Linting with Stylelint must pass without errors or warnings for any CSS task to be considered complete
-
 ## CSS Styleguide
 ### Class naming
 - Use **kebab-case** for CSS class names, NOT camelCase (even with CSS modules)
   - Example: `.content-type` NOT `.contentType`
 - Variations use `--` between base class name and variant name
   - Example: `.component--variation`
 
-### CSS Rules
-Always use CSS logical properties instead of physical directions.
-
 ### Breakpoints
 Defined in `source/00-config/vars/breakpoints.css` using custom media queries
 Max-width variants are also available (e.g., `--tablet-max`, `--desktop-max`).

agent_docs/headless_cms.md → agent_docs/nextjs/headless_cms.md

@@ -1,4 +1,7 @@
-# Headless CMS Setup
+---
+title: Headless CMS Setup
+description: Read when told to set up the headless Drupal or headless Wordpress starter kit
+---
 
 ## Drupal
 ```bash

agent_docs/react_component_conventions.md → agent_docs/nextjs/react_component_conventions.md

@@ -1,4 +1,7 @@
-# React Component Conventions
+---
+title: React component conventions
+description: Read when creating a React component in `source`
+---
 
 This file provides information about a React component's file structure.