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, 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.
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, capture visible-tab screenshots, accept Gitea-friendly file attachments, and include Chrome profile: Silma in created issue bodies.
If the Ready checkbox is checked, create the issue first, upload screenshots/files as issue assets second, and apply the ready label last.
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.

4.3 KiB Raw Blame History