# Gitea Codex Context

This file is Codex's persistent operating context for this repository.

Related orientation documents:
- Full project change log: `./.codex-history.md`
- Persistent implementation map: `./.codex-project-map.md`
- Raw structural baseline: `./.ai-structure.md`

## Recommended Read Order

1. `./.codex-context.md`
2. `./.codex-project-map.md`
3. The concrete files involved in the current task
4. `./.codex-history.md` only through targeted search, tags, or the latest relevant entries

## High-Value Project Anchors

- App entry point and default version wiring: `main.go`
- Web command and server startup: `cmd/web.go`
- Installed-instance initialization and route mounting: `routers/init.go`
- Main web router: `routers/web/web.go`
- Authentication handlers: `routers/web/auth/`
- Request context, session, template data, and response helpers: `services/context/`
- Domain business logic: `services/`
- Persistence, DB infrastructure, and migrations: `models/`, `models/db/`, `models/migrations/`
- Server-side UI templates: `templates/`
- Browser-side JS/CSS/frontend: `web_src/`

For detailed request flow, auth flow, extension points, and task-oriented entry points, use `./.codex-project-map.md` instead of duplicating them here.

## Persistent Workflow Rules

- Update `./.codex-history.md` after real project code changes.
- Do not add Codex-only preference or memory edits to `./.codex-history.md`.
- Do not reread unchanged context files within the same session unless the current task explicitly depends on them.
- Prefer targeted search in `./.codex-history.md` by keyword, tag, or subsystem before reading larger ranges.
- When the user asks for `revert`:
  - first show the latest 10 commits as a numbered list with short descriptions;
  - wait for the user's numeric choice before doing anything;
  - if the target change is not committed, explain that the safe path is `git restore`, not `git revert`.
- Revert flows must stay non-destructive by default; prefer `git revert` for committed changes and avoid destructive reset-style actions unless the user explicitly asks for them.

## Persistent `.codex-history.md` Rules

- Numeric IDs are reserved only for real project code changes.
- IDs start at `0` and increase sequentially by `1`.
- Use the format `N - [YYYY-MM-DD HH:MM:SS]`.
- Store the real repository-derived application version, without a `Version:` label.
- Keep only the final consolidated result of a task; do not keep intermediate attempts or failed correction steps.
- Append to the same task only while the changes are consecutive follow-ups to the same problem.
- If unrelated tasks happened in between, record the new work as a new task even if it returns to the same area.

## Persistent Communication Preferences

- After finishing a task, respond briefly and directly unless there are blockers or problems.
- Re-check the rules in this file before and after making changes.

## Current Working Notes

- This workstation has limited CPU and RAM resources; prefer targeted, lower-scope test runs first and avoid unnecessarily heavy concurrent verification unless the task truly requires it.
- `main.go` defaults `setting.AppVer` to `development`; derive the real build/version string from the repository when writing `./.codex-history.md`.
- The repository is predictably split across `cmd/`, `routers/`, `services/`, `models/`, `templates/`, and `web_src/`, so changes should normally stay localized to one or two layers plus their tests.
- For custom release maintenance and repo-sync tasks, consult `./.codex-script-notes.md` before reanalyzing the large helper scripts.
- New UI-visible functionality in this fork often also requires locale updates, so UI tasks and related history searches should usually consider `options/locale/`, especially `locale_en-US.json` and any actively maintained translated locale files.

- History rule: all changes for the same `git describe` version must be recorded under the same `.codex-history.md` entry; create a new history entry only when the version string changes.