# AI Continuation Guide

This file is the entrypoint for any AI or engineer continuing the repository.

## Start Here

Run these commands before changing anything:

```bash
git status --short --branch
git log -5 --oneline --decorate
python3 tools/check_project.py
sed -n '1,260p' docs/06-project-status.md
sed -n '1,260p' docs/07-exploration-history.md
sed -n '1,260p' docs/08-next-work.md
```

The active branch and remote are normally:

```text
branch: main
remote: https://git.k1412.top/wuyang/agent.git
```

Do not assume the public web service is running just because the repository is healthy. Check it separately:

```bash
web/manage.sh status
curl -fsS https://lab.k1412.top/api/health | jq
curl -fsS https://agent-eval.k1412.top/health
```

## Actual Goal

This is not merely a paper browser. The user wants a scaffold that turns a large raw corpus into personal, reusable cognition:

1. remember important knowledge;
2. compress it into a coherent system;
3. use that system to explain causes, compare approaches, answer new questions, and propose designs.

The current Atlas is a corpus exploration prototype, not a validated solution to this goal. The user rated its practical learning value at effectively zero because browsing left no durable learning state. Do not spend the next iteration polishing the graph without addressing this gap.

The current immediate research question is Agent completion, verification, and recovery. Read
`research/completion-verification/findings.md` and `evidence-ledger.md` before extending the Agent
evaluation work. A document-style web rendering now exists at `https://agent-eval.k1412.top/`;
the old v1 evaluation report is archived at `/evaluation-v1.html`. Agent experiments and product-level
web redesign remain paused until the user challenges and accepts or revises the conclusions.

## Truth Hierarchy

Treat repository artifacts according to their evidence level:

1. `research/*/findings.md` and `evidence-ledger.md`: current evidence-backed conclusions.
2. `experiments/*`: method, failures, and validation boundaries.
3. `docs/`: stable system-level knowledge, but verify dates and sources before extending it.
4. `papers/items/*.md` with `status: skimmed`: partially reviewed.
5. `papers/items/*.md` with `status: queued`: collection records only, not understood papers.
6. Auto tags and model screening outputs: high-recall triage, never final truth.

The old `learning/agent-memory/` module is retained as a failed experiment. It is not the current synthesis.
The Agent evaluation design under `research/evaluation/` is an implementation contract, not a completed
benchmark. Its task contracts explicitly mark which runners do not exist yet.
`evaluation-site/` is a presentation layer for that contract. It must not introduce stronger claims than
the research artifact or display simulation values as real benchmark results.
The completion-certificate, failure-object, and recovery-router design in
`research/completion-verification/findings.md` is a cross-paper inference, not a validated implementation.
The existing evaluation contract must be revised against that research before runner work resumes.

## Repository Contracts

- Keep jobs, papers, and industry practice as separate first-class streams.
- Use metadata and indexes for cross-cutting organization; do not make deep directories the primary UX.
- Preserve original sources and raw traces. A summary must not overwrite evidence.
- Distinguish collection, screening, full-text evidence, synthesis, and user learning state.
- Run `python3 tools/collection/build_index.py` after changing item frontmatter.
- Run `python3 tools/check_project.py` and `git diff --check` before committing.
- Use `python3`, not `python`, in this environment.
- Keep generated cache and PID/log files under `web/cache/`; they are intentionally ignored.
- Never commit credentials. Git authentication is configured outside the repository.

## Model API Contract

Default internal llama.cpp endpoints:

```text
Luna:      http://192.168.1.10:11435/v1
Terra/Sol: http://192.168.1.10:11436/v1
```

Current model tiers are configurable with:

```text
MODEL_LIGHT=ChatGPT-5.6:Luna
MODEL_FAST=ChatGPT-5.6:Terra
MODEL_LARGE=ChatGPT-5.6:Sol
```

Luna runs on the NAS AMD iGPU. Terra and Sol are aliases of one resident llama.cpp runner on the V100 32G. The application serializes model calls and must not override server context sizing. Expensive `Sol` actions should remain explicit, not automatic.

## Common Commands

```bash
# Rebuild the main index
python3 tools/collection/build_index.py

# Validate repository integrity
python3 tools/check_project.py

# Start or inspect the web service
web/manage.sh start
web/manage.sh status
web/manage.sh logs

# Research pipeline help
python3 tools/research/search_arxiv_memory.py --help
python3 tools/research/screen_memory_corpus.py --help
python3 tools/research/build_memory_landscape.py --help

# Collection fallback when the arXiv export API is unavailable
python3 tools/collection/collect_arxiv.py --backend search-html --help

# Aggregate Agent evaluation result JSONL
python3 tools/evaluation/score_agent_runs.py --help

# Regenerate/check the completion research evidence browser
python3 evaluation-site/build_research_data.py
python3 evaluation-site/build_research_data.py --check

# Preview the research document and archived v1 report
python3 -m http.server 4173 --directory evaluation-site
```

Read the scripts before rerunning network or model-heavy research jobs. The committed research data is the reproducible snapshot; a refresh changes the time boundary and may be expensive.

## Before Handoff

After meaningful work, update all affected layers:

- artifact or code;
- generated index/data if applicable;
- experiment record for the method and result;
- `docs/06-project-status.md` for current facts;
- `docs/07-exploration-history.md` for a new major decision or failed route;
- `docs/08-next-work.md` for changed priorities.

Commit with a narrow message and push `main` unless the user requests another branch.
