docs(P2): add TODO/debt conventions and mark known debt

AGENTS.md

@@ -80,6 +80,10 @@ For a custom browser, set `PLAYWRIGHT_CHROMIUM_EXECUTABLE`.
 - Do not copy GPL code. See `docs/mit-upstream-guidelines.md`.
 - Never paste or preserve PATs/tokens. See `SECURITY.md`.
 - If you change generated docs or behavior, update `CHANGELOG.md`.
+- Mark intentional shortcuts and known debt with `TODO(P<n>): <message>` or
+  `TODO: <message> (debt: <area>)`. Use `P0` only for urgent safety/correctness
+  follow-ups, `P1` for reliability/performance debt, and `P2` for maintainability
+  debt. Prefer `// TODO` comments for code and `<!-- TODO -->` for Markdown.
 
 ## Important Specs
 

CLAUDE.md

@@ -59,4 +59,7 @@ mapping and `README.md` for longer verification notes.
 - Do not reset or discard existing changes unless explicitly asked.
 - Keep edits focused and update `CHANGELOG.md` for release-facing behavior.
 - Never paste or preserve tokens. Follow `SECURITY.md`.
+- Mark known technical debt with `TODO(P<n>): <message>` or
+  `TODO: <message> (debt: <area>)`. Use priorities `P0/P1/P2` to match the
+  severity convention in `AGENTS.md`.
 

src/main.ts

@@ -129,6 +129,7 @@ export default class AI3DModelWorkbench extends Plugin {
     // Views are cleaned up by Obsidian calling onClose()
   }
 
+  // TODO(P2): extract into src/view/heading-pin-observer.ts and unit-test the selector/event wiring (debt: view-layer).
   private setupHeadingPinObserver(): void {
     const markdownContainerSelector = ".markdown-preview-view, .markdown-source-view";
     const headingSelector = [

src/render/babylon/scene.ts

@@ -229,6 +229,8 @@ function buildObjTextureCandidates(modelDir: string, rawPath: string, modelPath:
   return candidates;
 }
 
+// TODO(P2): split this class into loader/camera/light/annotation helpers.
+// Scene class is >1,700 lines and mixes rendering, interaction, and fallback logic (debt: renderer-babylon).
 export class BabylonModelPreview implements WorkbenchPreview {
   private static readonly annotationIdentity = Matrix.Identity();
   private static readonly annotationWorldPoint = Vector3.Zero();

src/render/three/scene.ts

@@ -200,6 +200,8 @@ function getObjectPreviewBounds(object: Object3D) {
   );
 }
 
+// TODO(P2): decompose this class into loader/camera/light/annotation modules.
+// Scene class is >2,000 lines and mixes rendering, interaction, and knowledge capture (debt: renderer-three).
 export class ThreeModelPreview implements WorkbenchPreview {
   private readonly renderer: WebGLRenderer;
   private readonly scene: Scene;

src/settings.ts

@@ -13,6 +13,8 @@ import { getRuntimeProcess } from "./utils/node-shim";
 
 const proc = getRuntimeProcess();
 
+// TODO(P2): split display() into section-builder methods; currently >500 lines (debt: settings-ui).
+
 function getConverterCommandPlaceholders(): {
   python: string;
   freecad: string;

src/view/direct-view.ts

@@ -26,6 +26,8 @@ export const DIRECT_VIEW_TYPE = "ai3d-direct-view";
 const log = createLogger("direct-view");
 const THREE_WORKBENCH_DIRECT_EXTS = new Set(["glb", "gltf"]);
 
+// TODO(P2): migrate direct setState calls into typed PluginStore actions (debt: store-api).
+
 function createDefaultProfile(): ModelAssetProfile {
   return { tags: [], notes: "", annotations: [], createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() };
 }