docs(agents): issue-tracker and domain guidance for agents; ignore .pi session state

.gitignore

@@ -1,4 +1,5 @@
 __pycache__/
+.pi/
 *.pyc
 .commandcode/
 data/fenris.pid

AGENTS.md

@@ -0,0 +1,9 @@
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked in Gitea using the authenticated `tea` CLI. See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+This is a single-context repository. See `docs/agents/domain.md`.

docs/agents/domain.md

@@ -0,0 +1,26 @@
+# Domain Docs
+
+How engineering skills should consume this repository’s domain documentation.
+
+## Layout
+
+This is a single-context repository:
+
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+└── ...
+```
+
+## Before exploring
+
+Read `CONTEXT.md` and relevant ADRs under `docs/adr/` when they exist. If they do not exist, proceed silently. Domain-modeling skills create them lazily when terminology or durable architectural decisions are resolved.
+
+## Use the glossary’s vocabulary
+
+Use terminology defined in `CONTEXT.md` consistently. If required terminology is missing or contradictory, raise it through domain modeling rather than silently inventing synonyms.
+
+## Flag ADR conflicts
+
+If proposed work contradicts an existing ADR, identify the conflict explicitly instead of silently overriding it.

docs/agents/issue-tracker.md

@@ -0,0 +1,85 @@
+# Issue tracker: Gitea
+
+Issues for this repository live in Gitea at:
+
+https://git.bongbetic.com/xavierk/Fenris/issues
+
+Use the authenticated `tea` CLI from the repository root. The configured login is `xavierk`.
+
+## General operations
+
+- List: `tea issues list`
+- Read: `tea issues <index> --comments`
+- Create: `tea issues create --title "<title>" --description "<body>"`
+- Edit: `tea issues edit <index> --title "<title>" --description "<body>"`
+- Assign: `tea issues edit <index> --add-assignees "<username>"`
+- Add labels: `tea issues edit <index> --add-labels "<labels>"`
+- Comment: `tea comments add <index> --description "<comment>"`
+- Close: `tea issues close <index>`
+- Reopen: `tea issues reopen <index>`
+
+Use `--output json` for machine-readable list and read operations. Use `tea api` when the high-level issue commands do not expose a native Gitea operation.
+
+## When a skill says “publish to the issue tracker”
+
+Create a Gitea issue in this repository. Preserve Markdown formatting in its body and apply any labels required by the invoking skill.
+
+## When a skill says “fetch the relevant ticket”
+
+Read the named issue with comments. The user may provide its URL, title, or index. In user-facing output, refer to issues by their linked titles rather than bare indices.
+
+## Wayfinding operations
+
+Wayfinder maps and decision tickets are Gitea issues.
+
+### Map and ticket grouping
+
+- A map has the label `wayfinder:map`.
+- Create one milestone named `Wayfinder: <map title>` for the effort.
+- Assign the map and all its tickets to that milestone.
+- Every ticket links its parent by name near the top: `Parent map: [<map title>](<map URL>)`.
+- Every ticket has exactly one type label: `wayfinder:research`, `wayfinder:prototype`, `wayfinder:grilling`, or `wayfinder:task`.
+
+The shared milestone and explicit parent link express the child relationship, because this Gitea version has no native parent/child issue API.
+
+### Blocking
+
+Use Gitea’s native issue-dependency relationship. To make `<blocked>` depend on `<blocker>`:
+
+```bash
+tea api -X POST \
+  repos/{owner}/{repo}/issues/<blocked>/dependencies \
+  -F index=<blocker> \
+  -f owner=xavierk \
+  -f repo=Fenris
+```
+
+List blockers:
+
+```bash
+tea api repos/{owner}/{repo}/issues/<index>/dependencies
+```
+
+Remove the relationship with the same payload and `-X DELETE`.
+
+### Frontier
+
+List open issues in the map’s milestone. Exclude:
+
+- the issue labelled `wayfinder:map`
+- assigned tickets, because assignment is the claim
+- tickets whose dependency query returns any open issue
+
+The remaining open, unassigned, unblocked tickets are the frontier. Choose the oldest first unless the user names one.
+
+### Claim
+
+Before doing any ticket work, assign it to the current `tea whoami` user. An open ticket without an assignee is unclaimed.
+
+### Resolve
+
+1. Add the answer as a resolution comment.
+2. Close the ticket.
+3. Re-fetch the map immediately before editing it.
+4. Append a linked one-line context pointer to `Decisions so far`.
+5. Create newly visible tickets, then wire dependencies in a second pass.