# Repository Guidelines

## Project Structure & Module Organization
`docs/` is the main source of product, architecture, integration, and team-process documentation. Keep active engineering documents in `docs/*.md`; presentation exports belong under `docs/archive/领导演示资料/`. `frontend/archive/sgClaw验证-已归档/` contains the historical Vue 2 verification page (`index.html`, `index.vue`) plus helper scripts (`serve.sh`, `download-libs.sh`, `testRunner.js`). `frontend/README.md` and `docs/README.md` describe what is active versus archived.

## Build, Test, and Development Commands
There is no formal build system in the repository today. Use the local verification page directly:

- `bash frontend/archive/sgClaw验证-已归档/serve.sh`
  Starts a local HTTP server on port `8080` by default.
- `bash frontend/archive/sgClaw验证-已归档/serve.sh 9090`
  Serves the verification page on a custom port.
- `bash frontend/archive/sgClaw验证-已归档/download-libs.sh`
  Downloads Vue 2.6.14 and Element UI assets into `frontend/archive/sgClaw验证-已归档/lib/` for offline use.

Open `http://localhost:8080/index.html` after starting the server.

## Coding Style & Naming Conventions
Match the existing style in each file. Frontend code uses 2-space indentation, semicolon-free JavaScript, and simple Vue 2 patterns. Shell scripts should stay Bash-compatible, include `set -e`, and keep usage notes at the top. Preserve existing Chinese file names and domain terminology; add new docs with concise, descriptive names such as `L5-xxx.md` or `xxx_printable.md` when extending the documentation set.

## Testing Guidelines
Testing is currently manual and centered on `frontend/archive/sgClaw验证-已归档/testRunner.js`. Validate changes by serving the page, running the relevant verification flows, and recording whether the change affects external API checks, internal browser integration checks, or end-to-end scenarios. If a change touches archived presentation assets, verify links and exported files still open correctly.

## Commit & Pull Request Guidelines
Git history currently contains only `first commit`, so no strong convention is established yet. Use short imperative commit subjects, for example `docs: update browser integration notes` or `frontend: adjust verification report layout`. PRs should include a clear summary, affected paths, manual validation steps, and screenshots when `frontend/archive/sgClaw验证-已归档/` UI output changes. Link related docs or issues when the change updates architecture or process guidance.

## Security & Configuration Tips
Do not commit real API keys. The verification page expects runtime globals such as `window.__SGCLAW_TEST_OPENAI_KEY__` and `window.__SGCLAW_TEST_CLAUDE_KEY__`; keep them in local test-only setup, not tracked files.