Repo sync

src/ai-tools/README.md

@@ -1,56 +1,183 @@
 # AI-powered tools
 
-A CLI tool for using AI to edit documentation according to defined prompts.
+The ai-tools subject provides CLI tools for using AI to edit and refine documentation based on prompt-driven guidelines. It integrates with GitHub Models API to apply automated improvements to content files.
 
-This tool refines content files using AI based on an (extensible) set of prompt-driven guidelines. The default is versioning refinement. In the future we might add: scannability, readability, style, technical accuracy.
+## Purpose & Scope
 
-This script calls the [Models API](https://docs.github.com/en/rest/models/inference?apiVersion=2022-11-28#run-an-inference-request). It requires a personal access token with Models scopes in your `.env` file.
+This subject is responsible for:
+- AI-powered content refinement (versioning, intro, etc.)
+- Prompt-driven content editing with LLMs
+- Integration with GitHub Models API
+- Copilot Spaces export and conversion to prompts
+- Automated content quality improvements
+- Extensible prompt system for different refinement types
 
-## Usage
+Current refinements: versioning, intro. Future: scannability, readability, style, technical accuracy.
 
-```sh
-<<<<<<< HEAD:src/ai-editors/README.md
-tsx src/ai-editors/scripts/ai-edit.ts --editor <type> --response <type> --files <file1.md>
-||||||| 5ae4ec0f5cb:src/ai-editors/README.md
-tsx src/ai-editors/scripts/ai-edit.js --editor <type> --response <type> --files <file1.md>
-=======
+## Architecture & Key Assets
+
+### Key capabilities and their locations
+
+- `scripts/ai-tools.ts` - Main CLI tool for running AI refinements
+- `lib/call-models-api.ts` - Client for GitHub Models API inference
+- `lib/prompt-utils.ts` - Loads prompts and executes refinements
+- `prompts/*.md` - Prompt templates for different refinement types
+
+## Setup & Usage
+
+### Requirements
+
+Add GitHub token with Models scopes to `.env`:
+
+```bash
+GITHUB_TOKEN=ghp_your_token_here
+```
+
+### Running refinements
+
+```bash
 # Direct command
-tsx src/ai-tools/scripts/ai-tools.ts --refine <type> --files <file1.md>
+tsx src/ai-tools/scripts/ai-tools.ts --refine versioning --files content/path/to/file.md
 
-# Or via npm script
-npm run ai-tools -- --refine <type> --files <file1.md>
->>>>>>> origin/main:src/ai-tools/README.md
+# Via npm script
+npm run ai-tools -- --refine versioning --files content/path/to/file.md
 ```
 
-* `--files, -f`: One or more content file paths to process (required).
-* `--refine, -r`: Specify one or more refinement types (default: `versioning`).
+### Options
 
-**Examples:**
+- `--files, -f`: One or more content file paths (required)
+- `--refine, -r`: Refinement type(s) - `versioning`, `intro` (default: `versioning`)
+- `--write, -w`: Write changes to files (default: false, shows diff only)
+- `--verbose, -v`: Verbose output for debugging
+- `--space, -s`: Use Copilot Space as prompt
+- `--exportSpace`: Export Copilot Space to prompt file
 
-```sh
-<<<<<<< HEAD:src/ai-editors/README.md
-tsx src/ai-editors/scripts/ai-edit.ts --files content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md --editor versioning --response list
-||||||| 5ae4ec0f5cb:src/ai-editors/README.md
-tsx src/ai-editors/scripts/ai-edit.js --files content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md --editor versioning --response list
-=======
-# Direct command
-tsx src/ai-tools/scripts/ai-tools.ts --files content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md --refine versioning
+### Examples
 
-# Via npm script  
-npm run ai-tools -- --files content/copilot/tutorials/coding-agent/get-the-best-results.md --refine intro
->>>>>>> origin/main:src/ai-tools/README.md
+Refine versioning in a file:
+```bash
+npm run ai-tools -- --files content/copilot/tutorials/coding-agent/get-the-best-results.md --refine versioning
 ```
 
-## Requirements
+Refine intro:
+```bash
+npm run ai-tools -- --files content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md --refine intro
+```
+
+Multiple files:
+```bash
+npm run ai-tools -- --files file1.md file2.md file3.md --refine versioning
+```
+
+Write changes (not just preview):
+```bash
+npm run ai-tools -- --files content/path/to/file.md --refine versioning --write
+```
+
+## Data & External Dependencies
+
+### Data inputs
+- Content markdown files with frontmatter
+- Prompt templates in `prompts/` directory
+- GitHub Models API for inference
+
+### Dependencies
+- GitHub Models API - Requires `GITHUB_TOKEN` with Models scopes
+- `commander` - CLI argument parsing
+- `dotenv` - Environment variable loading
+- Copilot Spaces (optional) - Can export/import prompts
+
+### Data outputs
+- Refined markdown content (preview or written to files)
+- Diffs showing proposed changes
+- Merged frontmatter updates
+
+## Cross-links & Ownership
+
+### Related subjects
+- [`src/content-render`](../content-render/README.md) - Content parsing and rendering
+- Content files in `content/` - Target of refinements
+
+### Internal documentation
+- [GitHub Models API docs](https://docs.github.com/en/rest/models/inference)
+- Copilot Spaces for prompt management
+
+### Ownership
+- Team: Docs Content (for use and development)
+- Note: These tools are for the docs-content team. We welcome them to use Copilot to support and develop these tools, but docs-engineering is largely hands off.
+
+## Current State & Next Steps
+
+### Available refinement types
+
+Current prompts:
+- `versioning` - Refines version-related content
+- `intro` - Improves article introductions
+
+Each prompt defines:
+- Instructions for the LLM
+- Expected output format
+- Quality criteria
+
+### Adding new refinements
+
+1. Create prompt file in `prompts/` (e.g., `readability.md`).
+2. Write prompt instructions and examples.
+3. Test with Models UI first.
+4. Use `--refine readability` to apply.
+
+Prompt template in `prompts/prompt-template.yml`.
+
+### Copilot Spaces integration
+
+Export Space to prompt:
+```bash
+npm run ai-tools -- --exportSpace space-id --output prompts/my-prompt.md
+```
+
+Use Space as prompt:
+```bash
+npm run ai-tools -- --space space-id --files content/path/to/file.md
+```
+
+### Known limitations
+- Requires GitHub token with Models scopes
+- API rate limits apply
+- Quality depends on prompt engineering
+- Currently manual execution (not in CI)
+- No automated testing/evals yet
+
+### Best practices
+
+**Prompt engineering:**
+- Test prompts in GitHub Models UI first
+- Include clear examples in prompts
+- Define expected output format
+- Iterate on prompts based on results
+
+**File selection:**
+- Start with single files to test
+- Use glob patterns for batch processing
+- Preview changes before writing
+
+**Quality assurance:**
+- Always review AI suggestions
+- Don't blindly accept all changes
+- Consider subject matter expertise needed
+- Test refined content for correctness
+
+### Troubleshooting
 
-* A valid `GITHUB_TOKEN` with Models scopes in your local `.env` file.
+**Missing token error:**
+Add `GITHUB_TOKEN` to `.env` with Models scopes.
 
-## Future development ideas
+**API errors:**
+- Check token permissions
+- Verify rate limits
+- Check Models API status
 
-* Add prompts to support all available editors.
-* Test prompts in Models UI and add evals to prevent regressions.
-* Enable running in CI.
-* Explore the new `llm` plugin for GitHub Models (see https://github.com/github/copilot-productivity/discussions/5937).
-* Add MCP for more comprehensive context.
-* Integrate with Copilot Edit mode in VS Code.
-* Add unit tests.
+**Poor refinement quality:**
+- Refine the prompt template
+- Add more examples
+- Test in Models UI first
+- Consider different model/parameters

src/app/README.md

@@ -0,0 +1,71 @@
+# App Router (`src/app`)
+
+This directory contains the [Next.js App Router](https://nextjs.org/docs/app) implementation for GitHub Docs. It currently serves as the application shell, handling the root layout, global providers, and 404 error pages, while coexisting with the Pages Router implementation.
+
+## Purpose & Scope
+
+The `src/app` directory is the entry point for the Next.js App Router. Its primary responsibilities are:
+- Defining the root HTML structure and metadata.
+- Initializing global client-side context providers (Theme, Locale, Languages).
+- Handling global "Not Found" (404) scenarios.
+- Providing a bridge between the modern App Router architecture and the `MainContext` used by existing components.
+
+We began this migration because we anticipate `@primer/react` will eventually drop support for the Pages Router. If that happens, we will be unable to upgrade `@primer/react`, effectively blocking us from receiving any future design system updates. Moving to the App Router prevents this and aligns us with the broader Next.js ecosystem.
+
+## Architecture & Key Assets
+
+### Directory Structure
+
+- `layout.tsx`: The server-side Root Layout. It sets up the `<html>` and `<body>` tags, loads global styles, and defines metadata/viewport settings.
+- `client-layout.tsx`: A client component (`'use client'`) that wraps the application in necessary React Context providers. This allows server components to compose client-side logic for theming and state management.
+- `not-found.tsx`: The UI for 404 errors within the App Router.
+- `lib/`: Utilities for context adaptation and routing logic.
+  - `app-router-context.ts`: Generates context data based on the current request path.
+  - `main-context-adapter.ts`: Adapts App Router data structures to match the `MainContext` shape, ensuring backward compatibility for components.
+- `components/`: Client-side components specific to the App Router shell (e.g., wrappers for 404 pages, context providers).
+
+### Key Concepts
+
+- **Context Adaptation**: Since much of the codebase relies on a monolithic `MainContext`, this directory implements adapters to construct a compatible context object from App Router primitives. This allows us to reuse existing components without rewriting them immediately.
+- **Hybrid Routing**: The application currently operates in a hybrid mode. While `src/app` defines the outer shell, many specific routes and page rendering logic may still reside in the Pages Router (`src/pages`) or are being incrementally migrated.
+
+## Setup & Usage
+
+### Development
+
+Standard Next.js App Router conventions apply. To add a new route using the App Router, create a folder with a `page.tsx` file inside `src/app`.
+
+Useful documentation:
+- [Next.js App Router Documentation](https://nextjs.org/docs/app)
+- [Migrating from Pages to App Router](https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration)
+
+### Testing
+
+Tests for App Router logic should be placed alongside the components if applicable.
+
+Tests that verify Next.js behavior (like 404 handling) can be found in `src/frame/tests/next.ts`.
+
+## Data & External Dependencies
+
+- **Data Sources**:
+  - Consumes UI strings and language data from `src/data-directory` (via `getUIDataMerged`).
+  - Uses `src/languages` for locale definitions.
+- **External Libraries**:
+  - `@primer/react`: Used for the design system and theming provider.
+  - `next`: The core framework.
+
+## Cross-links & Ownership
+
+- **Owner**: Docs Engineering
+- **Related Directories**:
+  - `src/pages`: The Pages Router implementation.
+  - `src/frame`: Server and middleware logic that interacts with routing.
+  - `src/data-directory`: Source of static data used in layouts.
+
+## Current State & Next Steps
+
+- **Current State**: The App Router handles the root layout and 404s. It provides a compatibility layer for existing contexts.
+- **Next Steps**:
+  - Migrate individual page routes from `src/pages` to `src/app`.
+  - Refactor components to reduce dependency on the monolithic `MainContext`.
+  - Improve data fetching patterns to use React Server Components (RSC) more effectively.