Add AGENTS and codex project conventions

AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS.md
+
+## Project Identity
+
+Project root: `/root/sourceserver/pbf`
+
+This repository is the NavSea PBF engineering, delivery, and audit workspace.
+
+Primary Git remote:
+
+- `origin -> ssh://git@nas:2222/tei/pbf.git`
+
+## First Files To Read
+
+When resuming work in this project, read in this order:
+
+1. [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)
+2. [`PROJECT_HANDOFF_2026-03-31.md`](/root/sourceserver/pbf/PROJECT_HANDOFF_2026-03-31.md)
+3. [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/NavSea_Delivery_Preflight_Audit_Spec.md)
+
+If the task is specifically about Domain work, also read:
+
+4. [`NavSea_Chart_Domain_Model_v1.md`](/root/sourceserver/pbf/NavSea_Chart_Domain_Model_v1.md)
+5. [`NavSea_Semantic_Package_Overlay_Design.md`](/root/sourceserver/pbf/NavSea_Semantic_Package_Overlay_Design.md)
+
+## Current Reliable Audit Baseline
+
+As of 2026-03-31:
+
+- the most reliable current delivery audit baseline is `Karatsu 10nm`
+- the trusted report is:
+  - [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.md`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.md)
+
+Important limitation:
+
+- `Karatsu 20nm delivery` is currently not object-auditable with the existing audit script because the delivery PBF no longer preserves enough trace-back anchor fields
+
+## Working Rules
+
+### 1. Step Record Must Stay Fresh
+
+Whenever there is meaningful progress, update:
+
+- [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)
+
+This includes:
+
+- after audits
+- after code fixes
+- after direction changes
+- before stopping at a meaningful checkpoint
+
+### 2. Commit Carefully
+
+This repository is often in a dirty working state.
+
+Rules:
+
+- never stage unrelated modified files
+- only commit files touched for the current task
+- do not sweep untracked audit artifacts into commits unless that is the explicit goal
+
+### 3. Preserve Audit Reality
+
+Do not present a delivery audit as trustworthy unless object identity is still recoverable.
+
+Current known-good object-level delivery audit pattern:
+
+- use `/home/wwwroot/pbf-delivery-karatsu-10nm`
+- use `--fid-key 'thisMyWorld@2026'`
+- use `--match-on-fid-only`
+
+### 4. Prefer Repo-Local Documentation
+
+When deciding what to do next, prefer repo-local docs over memory.
+
+Key references:
+
+- [`NavSea_Legacy_Field_Exit_Roadmap.md`](/root/sourceserver/pbf/NavSea_Legacy_Field_Exit_Roadmap.md)
+- [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/NavSea_Delivery_Preflight_Audit_Spec.md)
+- [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)
+
+## Resume Checklist
+
+At the start of a session:
+
+1. Read [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md).
+2. Check `git status --short --branch`.
+3. Confirm `git remote -v` still points to `nas`.
+4. Continue from the latest recorded next step.
+
+At the end of a session:
+
+1. Update [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md).
+2. If the checkpoint is useful, commit it.
+3. Keep unrelated dirty files out of the commit.

STEP_RECORD.md

@@ -12,6 +12,11 @@ Remote: `ssh://git@nas:2222/tei/pbf.git`
 - 已补交接文档：
   - [`PROJECT_HANDOFF_2026-03-31.md`](/root/sourceserver/pbf/PROJECT_HANDOFF_2026-03-31.md)
   - [`GIT_REMOTE_SWITCH_TO_NAS_2026-03-31.md`](/root/sourceserver/pbf/GIT_REMOTE_SWITCH_TO_NAS_2026-03-31.md)
+- 已补项目协作约定文件：
+  - [`AGENTS.md`](/root/sourceserver/pbf/AGENTS.md)
+  - [`codex/README.md`](/root/sourceserver/pbf/codex/README.md)
+  - [`codex/SESSION_START.md`](/root/sourceserver/pbf/codex/SESSION_START.md)
+  - [`codex/RESUME_PROMPT.md`](/root/sourceserver/pbf/codex/RESUME_PROMPT.md)
 - 已完成一次新的 delivery 审计，并确认哪条审计线可用
 
 ## Latest Audit Status

codex/README.md

@@ -0,0 +1,20 @@
+# Codex Project Notes
+
+This directory stores project-specific Codex working conventions.
+
+Use these files as the startup layer for future sessions in `pbf`.
+
+## Files
+
+- [`SESSION_START.md`](/root/sourceserver/pbf/codex/SESSION_START.md)
+  - what to read first when resuming work
+- [`RESUME_PROMPT.md`](/root/sourceserver/pbf/codex/RESUME_PROMPT.md)
+  - a ready-to-use prompt for continuing the project
+
+## Core Rule
+
+If there has been meaningful progress, update:
+
+- [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)
+
+That file is the current source of truth for "where we stopped last time."

codex/RESUME_PROMPT.md

@@ -0,0 +1,5 @@
+# Resume Prompt
+
+Use this prompt to continue the project quickly:
+
+`继续处理 /root/sourceserver/pbf/STEP_RECORD.md 里记录的下一步，先读 STEP_RECORD.md 和 AGENTS.md，再从 Karatsu 10nm delivery 审计的 baseline / depth / navigation marks 三组问题开始修。`

codex/SESSION_START.md

@@ -0,0 +1,47 @@
+# Session Start
+
+When opening this project again, do this first:
+
+1. Read [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md).
+2. Read [`AGENTS.md`](/root/sourceserver/pbf/AGENTS.md).
+3. Run:
+
+```bash
+cd /root/sourceserver/pbf
+git status --short --branch
+git remote -v
+sed -n '1,220p' STEP_RECORD.md
+```
+
+## Current Resume Target
+
+Unless a newer step record says otherwise, continue from:
+
+- `Karatsu 10nm delivery` audit follow-up
+- priority groups:
+  - `baseline`
+  - `depth / bathymetry`
+  - `navigation marks`
+
+## Audit Reminder
+
+The current trusted delivery audit line is:
+
+```bash
+.venv/bin/python navsea_render_audit.py \
+  --audit-name navsea_original_vs_delivery_karatsu_10nm_20260331 \
+  --comparison-label 'delivery版' \
+  --fid-key 'thisMyWorld@2026' \
+  --match-on-fid-only \
+  --original-style /root/sourceserver/pbf/src/pbf/style.json \
+  --engineering-style /root/sourceserver/pbf/src/pbf/style.navsea-delivery-karatsu-10nm.json \
+  --original-tile-root /home/wwwroot/newpec/exported_auto/tile.mapple-on.jp__newpec-mvt-20260106__z___x___y_.pbf/tiles \
+  --engineering-tile-root /home/wwwroot/pbf-delivery-karatsu-10nm \
+  --report-md /root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.md \
+  --report-json /root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.json \
+  --skip-db-persist
+```
+
+## Stop Rule
+
+Before ending a work session, update [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md).