viexp/AGENTS.md

AGENTS.md — viexp

viexp is a terminal file manager for Linux written in Rust — a ranger-inspired successor (async I/O, native image previews, script-first extension model). It is also a guided learning project: the owner is learning Rust from scratch and practicing technical English, one 20-hour sprint at a time (Josh Kaufman's "First 20 Hours"). License: GPL-3.0-or-later. Chat with the owner happens in Russian; everything that lands in the repo is English.

Repo state: docs only, no Rust code yet

• This is the planning stage of viexp (a Rust terminal file manager). There is no Cargo.toml — cargo commands will fail. Bootstrapping the cargo skeleton is itself the first task (docs/tasks/0001, Gitea issue #1), per Sprint 0 in docs/roadmap.md.
• The repo doubles as an Obsidian vault: all project knowledge lives in docs/ (tracked in git); .obsidian/ itself is gitignored. docs/index.md is the vault map.
• Detailed workflow docs live in docs/workflows/ (research, Gitea, English) — read them before changing vault or issue structure.

Language is a hard constraint

• Everything user-visible — vault notes, issues, commit messages, later code comments — is English on purpose (the project is an English-immersion environment). Never translate existing English docs or write new ones in Russian.
• Commits: Conventional Commits in English, e.g. feat(preview): add kitty graphics support.

Vault conventions (docs/)

• Note filenames: kebab-case English. Frontmatter type and status are required (filtering depends on them); build new notes from the templates in TMP/ and keep headings stable per note type (Obsidian folding assumes identical structure).
• Task statuses: todo | in-progress | blocked | review | done | cancelled; priorities P0–P3.
• Traceability rule: every decisions/ ADR must link at least one research/ note; every tasks/ note links a decision or the roadmap.
• Task notes mirror Gitea issues — store the issue number in the task's gitea-issue frontmatter property (see docs/tasks/0001 for the pattern).

Gitea (git.v-port.ru/vaskes/viexp)

• CLI: tea (logged in as vaskes). Scripts in scripts/ read the API token from ~/.config/tea/config.yml — never hardcode tokens; .env/*.token are gitignored.
• Gitea 1.26.2 quirk: the issues API accepts labels by ID, not by name. Map names → IDs first (scripts/gitea-issues.sh does this).
• The project board (kanban) has no API on this instance — manage it only via the web UI. Board "Viexp": columns Backlog → To Do → In Progress → Done; the active sprint's issues live in To Do, next sprint's in Backlog.
• scripts/gitea-bootstrap.sh (labels + sprint milestones + seed issues; calls gitea-issues.sh) is re-runnable: existing labels/milestones/issues are detected and reused.
• Milestones = sprints (Sprint 0 — Setup & deconstruction …); labels: type/bug|feature|docs| research|chore|spike, priority/P0–P3, lang/english.

Git & verification

• Single long-lived branch main; work in branches named sprint-N/slug or feat/slug, squash-merged into main. One issue = one demoable outcome.
• Planned CI is a Sprint 0 deliverable and does not exist yet (no .gitea/workflows/). Once Rust code lands, CI and the verification order are: cargo fmt --check && cargo clippy -- -D warnings && cargo test.
• Roadmap rule that binds agents too: never leave the repo in a broken state — small commits, one drill/slice per commit.

Rust conventions (apply from Sprint 0 onward)

• No unwrap()/expect() outside tests; thiserror for domain errors, anyhow at the main boundary; prefer ? with context over match-heavy plumbing.
• This is a learning codebase: choose the simplest readable solution over clever idioms. When introducing a new concept (borrowing, traits, async), explain it briefly — in the PR description or a docs/learning/ note.
• Comments explain why (constraints), never narrate what.

Working a sprint session (assistant role)

1. Start by reading the current sprint note (docs/sprints/sprint-NN-*.md) and the latest DevLog entry; continue from where they point, not from scratch.
2. Pick the next open issue from the sprint's milestone; keep the board column in sync.
3. One drill (20–30 min) ≈ one commit; get each diff reviewed quickly — the review is the feedback loop the whole method depends on.
4. In code review: point at concrete lines, translate the compiler's complaint into plain words (Russian in chat, English in artifacts), and for recurring error classes add a self-correction cue to the ErrorJournal (TMP/ErrorJournal.md pattern).
5. Frustration rule: stuck >20 minutes on one error → shrink the drill instead of grinding.
6. Do not commit or push unless the owner asks. Do not close issues without a demoable result.