# Git-first project documentation The project's `git_repository_url` is the only repository configuration on a Project. Markdown under `docs/**/*.md`, plus root `README.md` and `AGENTS.md`, is authoritative in Git. The dashboard keeps a read-only SQLite index for the Documentation page and MCP; it never edits or pushes Markdown. ## Setup for self-hosted Gitea 1. Set each project's existing HTTPS Git repository URL. The Git server must advertise a default branch through `HEAD` and be reachable by the Django and MCP processes. 2. Set `PROJECT_DOCS_ALLOWED_GIT_HOSTS` to an explicit comma-separated host/port allowlist. The default is `git.jorendegraaf.eu`. Repository URLs with credentials, query strings, fragments, percent escapes, non-HTTPS schemes, or path traversal are rejected for syncing. Configure DNS/network access separately; a URL field alone does not grant access. 3. For private repositories, create a dedicated Gitea credential with **read-only repository contents** permission for each project. Gitea documents the [`read:repository` token scope](https://docs.gitea.com/1.27/development/api-usage/); verify that your instance also accepts the token for Git-over-HTTPS fetch. Store the mapping outside Git in the Django/MCP service environment as `PROJECT_DOCS_CREDENTIALS_JSON`, e.g. `{"":{"repository_url":"https://git.jorendegraaf.eu/owner/repo.git","username":"readonly-user","token":""}}`. The repository URL must match the project's configured URL exactly, binding that credential to one endpoint. Use a different credential per project. Protect the environment file, rotate tokens through Gitea, and restart both services after changes. No token is sent to the browser or returned by MCP. 4. Set `PROJECT_DOCS_MIRROR_ROOT` to a persistent, private directory outside any web/static alias, writable only by the app account. Its default is under `PROJECTS_PRIVATE_MEDIA_ROOT/git-docs`. Back up the database and mirror if historical reads are important. The current index can be rebuilt from Git; the shallow mirror holds only recent history. 5. Run migrations and restart Django and MCP. Open the project's **Documentation** link. An authorized read checks for a refresh when the configured interval has elapsed; an editor can use **Refresh from Git**. The default interval is 900 seconds. A manual refresh is limited to one attempt per 30 seconds. There is no cron, timer, worker queue, or webhook in this version, so an idle project is refreshed on its next authorized read. The fetch uses a private bare mirror, no working tree, no submodule checkout, no hooks, no scripts and no frontend build. It fetches the advertised default branch with depth 50, reuses the mirror for incremental fetches, and indexes only regular UTF-8 Markdown files in the approved paths. Limits default to 100 MiB per mirror, 5 MiB tree listing, 10 MiB total Markdown, 1 MiB per file and 500 files. Configure `PROJECT_DOCS_MAX_MIRROR_BYTES`, `PROJECT_DOCS_MAX_TREE_BYTES`, `PROJECT_DOCS_MAX_CONTENT_BYTES`, `PROJECT_DOCS_MAX_FILE_BYTES`, and `PROJECT_DOCS_MAX_FILES` if needed. The host needs Git and the Linux `prlimit` utility; Git commands have time, CPU and file-size limits. Redirects are disabled. A failed fetch/index leaves the last good database index intact and displays an error. ## What freshness means The UI and MCP distinguish the indexed commit, last successful fetch/index, most recently observed remote HEAD, and the documentation accuracy audit. A successful fetch proves the index matches the fetched Git commit; it does **not** prove Markdown claims still match code. A failed fetch preserves old content with a stale/error label. When the repo URL changes, the previous index remains visible but is marked stale until the new repository successfully indexes. The root `docs/.audit-state.json` is a **Codex workflow record in Git**, not the sync state. Its required fields are `schema_version`, `last_successful_audit` (UTC ISO timestamp), `audit_interval_days`, and `last_audited_commit` (full SHA). The dashboard reads it at the indexed commit and reports Unknown/Due when missing or invalid; it reports a commit mismatch when code has changed since the audit. Codex checks it at the start of card work. A user can manually request “audit docs now” to override the interval. The audit is bounded and opportunistic, never a cron or systemd job. Failed or partial audits record `last_attempt` and `last_status` without advancing the last successful audit. Run `python scripts/docs_audit.py` for a deterministic due/change/relative-link preflight, or `python scripts/docs_audit.py --force` for a manual override. It never edits state or declares semantic accuracy; Codex reviews relevant code and writes a report before advancing success fields. The initial baseline report is `docs/audits/2026-10-20.md`. Historical ZIP/wiki research under `docs/research/` is superseded for implementation. ## UI and MCP The Documentation page provides folder navigation, a sanitized Markdown view, search, source links, raw Markdown, and recent Git history for the current path. Relative Markdown links to indexed documents are rewritten to project-scoped routes; missing targets lose their link. Images and raw HTML are not rendered. Historical reads are limited to the retained shallow mirror and the same path; renamed and deleted files are not browsable in this version. Read-only MCP tools are `docs_list`, `docs_search`, `docs_read`, `docs_history`, and `docs_diff`. They use existing `projects:read` authorization and project membership. Search results return short snippets; reads return at most 250 lines or 30,000 characters with a continuation cue. Revisions must be retained commits for the requested path. MCP never returns Git credentials and does not accept arbitrary repository URLs or local filesystem paths. Codex working directly in a local checkout should read `docs/` there; remote clients use MCP. ## Recovery and rollback If fetches fail, check the configured host allowlist, the repository's default branch and access, private credential scope, and mirror permissions. The last good index remains available. A subsequent successful refresh atomically replaces it, including deletions. To rebuild a corrupted mirror, stop both services, move only that project's UUID-named mirror directory aside, then refresh. Keep its old directory until the new index is verified if historical reads matter. Deleting a project removes its mirror after the database transaction commits. Database migrations and the previous application version are the application rollback path; preserve a database backup before rolling back schema changes. No documentation changes are pushed by the web app.