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 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.
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 icon menu sections for Add URL, URLs, Gitea repos, Workspaces, Agents, Open Issues, and Add Issue.
Add URL 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.
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}}.
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 an agent file, capture visible-tab screenshots, accept multiple accumulated Gitea-friendly file attachments, and include Chrome profile: Silma plus the selected agent in created issue bodies.
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.
Newly created issues must be created with the Change Request label.
When creating an issue, upload the selected rendered agent file as an issue asset along with screenshots and files.
If the Ready checkbox is checked, create the issue first, upload the rendered agent file plus screenshots/files as issue assets second, and apply the ready label last.
Open Issues owns issue browsing and follow-up. It must list recent issues ordered by creation time, default to limiting the table to the active URL's linked repo, and provide a checkbox to show issues across all loaded repos.
Selecting an Open Issues row must show the original description, issue attachments, and comment chain, followed by 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.
Existing issue rows must allow applying the ready label and deleting the issue. Existing issue attachments must be removable. Deletion must require user confirmation.
Text-entry updates in Add Issue, Open Issues comments, and Agents 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, and keep the Ready checkbox label short.
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.

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.

6.2 KiB Raw Blame History