# AGENTS.md

## Project

`mp-silma-ai-aide` is a Vite + TypeScript Chrome extension scaffold. The built `dist/` directory is intended to be loaded in Chrome as an unpacked Manifest V3 extension.

## Required Reading

- Read `docs/extension-management.md` before doing Chrome extension loading, reloading, testing, browser automation, or profile-dependent work.
- Keep `AGENTS.md`, `llm.txt`, `manifest.llm.json`, `README.md`, and `docs/extension-management.md` in sync when commands, environment variables, deployable output, workflows, or extension-management rules change.

## Commands

- Install dependencies: `npm ci`
- Codex setup: `npm run codex:setup`
- Run local Vite dev server: `npm run dev`
- Run app in Codex: `npm run dev:codex`
- Build extension: `npm run build`
- Build extension in Codex: `npm run build:codex`
- Preview build output: `npm run preview`
- Verify generated extension output: `npm run verify:dist`

## Environment

Configuration is read from Vite environment variables:

- `VITE_GITEA_BASE_URL`: Base URL for the Gitea instance, for example `http://gitea.orson.tealthrone`.
- `VITE_GITEA_TOKEN`: Gitea API token.
- `VITE_GITEA_REPO_OWNER`: Target Gitea owner. Default: `jacob-mathison`.
- `VITE_GITEA_REPO_NAME`: Target Gitea repository. Default: `mp-silma-ai-aide`.

Use `.env.local` for local secrets. Keep `.env.local` and any real token-bearing env files out of git. Update `.env.example` when adding new required variables.

## Extension Build Notes

- `vite.config.ts` emits `dist/manifest.json` during production builds.
- `dist/` is the deployable output directory. Deployment or Chrome load-unpacked flows should point directly at `dist/`.
- `dist/` is generated output and should not be edited directly.
- Static extension assets live in `public/`; extension icon sources live under `public/icons/`.
- `scripts/generate-local-context.mjs` generates `public/local-context.json` from `/Users/Tabitha/.openclaw/workspace_Father` and configured local folder search roots before builds.
- `public/local-context.json` is a committed fallback snapshot so CI builds can still produce a self-contained `dist/` if the local workspace root is unavailable. It includes generated workspaces, Gitea worktrees, known URLs, and searchable folder candidates for workspace selection.
- `npm run build` runs `scripts/verify-dist.mjs` after Vite to ensure the generated output has the required extension files.
- Host permissions include `<all_urls>` for Chrome visible-tab screenshot capture plus the Gitea host derived from `VITE_GITEA_BASE_URL`. Rebuild after changing the base URL.
- Runtime API calls are centralized in `src/api.ts`.
- Side panel state is centralized in the vanilla Zustand store at `src/store.ts`.
- The extension opens as a Chrome side panel. It is not a draggable in-page window.
- The side panel has top-level toolbar sections for URLs, Gitea repos, Issues, Add Issue, and a management dropdown. Agents, Prompts, and Workspaces must live under the management dropdown rather than as separate toolbar buttons.
- Add URL must live inside the URLs view as a first-row Add URL button that opens a modal dialog. It is enabled only when the active tab's base URL is not already in the URLs list. The user must pick either a workspace or a Gitea repo; the app infers the linked counterpart from local context.
- URLs can be deleted from the URLs list. User-added URLs are removed from storage; generated known URLs are hidden through the stored deleted-base list. URL creation must happen through the modal dialog, not through a standalone Add URL menu item.
- The Agents view lists available agent files and must allow adding, editing, and deleting persisted agents from `chrome.storage.local`. At least one agent must remain available.
- The default `GLOBAL AGENT` is backed by `AGENTS.md` and contains agnostic handoff rules with template variables such as `{{git}}`, `{{workspace}}`, `{{url}}`, `{{baseUrl}}`, `{{profile}}`, and `{{issue}}`. It must tell downstream agents to close the Gitea issue after the implementation has been pushed, and to leave a Gitea issue comment when delivery is blocked, partial, or risky.
- The Workspaces view lists generated workspaces from `workspace_Father` plus user-added workspaces persisted in `chrome.storage.local` under `silmaAide.userWorkspaces`. It must show only a first-row Add workspace button for creation; that button opens a modal dialog. User-added workspaces must be selected from searchable generated folder candidates rather than by copy/pasting a path, and may be deleted from the side panel.
- The Prompts view manages workspace-scoped default prompts persisted in `chrome.storage.local` under `silmaAide.prompts`. Prompt records must include a name, workspace path, and content. When opening Prompts for a new prompt, the workspace selector should default to the active known URL's workspace/site when available.
- Add Issue is enabled only when the active tab's base URL is already in the URLs list and has a linked Gitea repo. The issue form must show the target repo, the active URL the extension believes it is attached to, let the user select a workspace prompt above Content, let the user select an agent file and issue labels, capture visible-tab screenshots, accept multiple accumulated Gitea-friendly file attachments, and include `Chrome profile: Silma` plus the selected agent in created issue bodies.
- The Add Issue default prompt dropdown must only show prompts attached to the active URL's workspace path. Selecting a prompt copies its content into the editable Content field for human adjustment.
- Created issue bodies must put the human-entered idea/change request under `# Requirements` and the generated source URL, base URL, workspace, repo, agent, and Chrome profile metadata under `# References`.
- Clicking a captured screenshot must open an expanded preview with Close, Remove, and Crop controls. The crop area should be a simple draggable/resizable box without a shaded crop fill, and the preview panel should use the available viewport without horizontal scrolling.
- Label options for issue creation and editing are `Change Request`, `Idea`, `Tabitha`, `Orson`, `Belisarius`, `Ozymandias`, and `Ready`.
- Newly created issues must default to the `Change Request` label unless the user changes the selected labels.
- When creating an issue, upload the selected rendered agent file as an issue asset along with screenshots and files.
- The old Ready checkbox must not be shown because `Ready` is now one of the selectable labels.
- Issues owns issue browsing and follow-up. It must list recent issues ordered by creation time, default to open issues for the active URL's linked repo, provide a checkbox to show issues across all loaded repos, provide Open and Closed status checkboxes as a multiselect, and provide an empty-by-default label filter.
- Selecting an Issues row must show a direct Open in Gitea link, a Send to Codex button that currently logs the selected issue payload, editable issue subject/content/label fields, issue attachments, and comment chain, followed by direct issue attachment controls plus a comment form that can add text, take additional screenshots, attach files, upload those files as issue assets, and submit a Gitea comment with attachment links.
- Clicking the selected Issues row again or clicking the detail close control must close the selected issue detail panel without deleting or changing the issue.
- Saving selected issue edits must use the selected issue's repo identity from Issues, include Gitea's current issue content version when available, verify the saved subject/content with a readback before reporting success, and must never fall back to the active tab's repo.
- Existing issue rows must allow deleting the issue. Existing issue labels must be editable from the selected issue form and saved through the Gitea issue labels endpoint. Existing issue attachments must be removable, and additional screenshots/files must be uploadable directly to the issue without creating a comment. Deletion must require user confirmation.
- Text-entry updates in Add Issue, selected issue edits, Issues comments, Agents, Prompts, workspace folder search, and Workspaces must not re-render the focused form control or blur the user while they type.
- Keep the Add Issue view dense; do not show the redundant view header title/description inside this view.
- The extension requests `activeTab` and `<all_urls>` host permission so screenshots can be captured from the current Chrome tab even after the side panel has stayed open across tab changes.
- Gitea API errors should include the failed operation and, for network-level failures, the configured Gitea API base URL plus actionable checks for env, extension host permissions, network/VPN access, token scope, and attachment size.

## Chrome Extension Management

- Use the Codex Chrome extension with the Chrome profile named `Silma` for this project.
- Do not use Chrome `Profile 1` for this project.
- Load or reload the unpacked extension from `dist/` only after running `npm run build`.

## Gitea Workflows

- `.gitea/workflows/build.yml` builds the deployable extension on pushes to `main` and pull requests.
- `.gitea/workflows/issue-opened-placeholder.yml` runs when a new issue is opened and prints `200 okay`.

## Coding Guidelines

- Keep the app TypeScript-first and strict.
- Prefer small, focused modules under `src/`.
- Do not commit secrets or generated build output.
- Run `npm run build` before handing off code changes.