# Agent Instructions

## Project

Coworker is a Windows-first local AI coding app with a Codex-style desktop UX, local model provider setup, an Odysseus-inspired Brain, and optional iPhone/iPad PWA access.

Repository:

```text
Code-Inc/Coworker
```

## Repository Rules

- Start every task with `git status --short --branch`.
- If the tree is clean, use a safe fast-forward update check before editing.
- Preserve unrelated user changes.
- Do not commit secrets, `.env` files, private keys, certificates, API tokens, local app data, or generated installers outside release artifacts.
- Use only Gitea Ubuntu runners for project builds, tests, dependency setup, package jobs, installers, and releases.
- Do not run dependency installs, Electron builds, test suites, package jobs, or installer builds on the user's local machine.
- Local checks are limited to lightweight reads and validation such as `rg`, JSON parsing, TypeScript config inspection, and `git diff --check`.
- Keep workflows on supported Gitea runner labels: `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`.
- Do not add Windows or macOS runners. Use Linux-compatible Electron packaging with Wine/Docker on Gitea runners.
- Keep release artifacts free of Codex kit metadata such as `AGENTS.md`, `.codex/`, workflow templates, and handoff docs.

## Commands

Run these through Gitea Actions, not locally:

```bash
npm install
npm run lint
npm run test
npm run build
npm run package:win
npm run audit
```

Lightweight local validation:

```bash
git diff --check
```

## Architecture Rules

- Electron + React + TypeScript is the product stack.
- Avoid native Node dependencies in v1 unless they have reliable Windows prebuilds and package cleanly from Ubuntu runners.
- The first installer target is unsigned NSIS `.exe`; MSI follows after the EXE pipeline is stable.
- Web/PWA access must be disabled by default and protected by pairing-code authentication.
- Workspace file access must stay inside explicitly selected project roots.
- Agent file writes, command execution, and destructive operations require visible user approval.

## Finish Checklist

- `git diff --check` passes.
- Gitea runner workflows are configured for build, security, dependency, cleanup, release dry-run, and template compliance.
- Release docs explain how the Windows installer is produced and where artifacts appear.
- If a commit is pushed and triggers workflows, poll the workflow to success or document the blocker.