Productize @sketchi-app/opencode-excalidraw docs + deterministic agent defaults

[anand-testcompare]

Objective

Finish remaining productization work for @sketchi-app/opencode-excalidraw after v0.0.7.

Current Status

Completed

• package publish/release automation landed (feat: package and automate @sketchi-app/opencode-excalidraw #128, chore(main): release opencode-excalidraw 0.0.7 #169)
• package/docs routing work landed (feat: add opencode lean docs page and package quickstart cleanup #138)
• .opencode harness de-tracking landed (refactor: retire .opencode harness and migrate diagram guidance #145)
• reliability hardening from first-run failures shipped in v0.0.7 (fix(opencode-excalidraw): stabilize diagram_grade under real harness #168)

Still Open

1. Output path policy hardening

   • default output root is still sketchi/png (packages/opencode-excalidraw/src/lib/output.ts)
   • move default to /.sketchi/sessions/<sessionID>/png/...
   • constrain tool-supplied outputPath to remain under default root by default
   • provide explicit opt-out for power users
   • ensure .sketchi/** is gitignored (including nested .gitignore if needed)

2. Deterministic package defaults

   • implement package-owned model/instruction defaults (no hidden reliance on local agent files)
   • add documented permission baseline + override mechanism

3. Docs consistency

   • align README/opencode docs with current install/output behavior
   • keep references/version labels current

4. Automated coverage

   • add tests for default session-scoped pathing
   • add tests for outputPath containment (bare filename + traversal attempts)
   • keep plugin CI gates enforcing this behavior

Non-Goals

• backend architecture changes for diagram endpoints

Consolidation

• create a .sketchi folder where generated excalidraw images go by default #137 remains closed as duplicate of this issue
• Refactor plugin dev workflow: de-track .opencode harness logic and adopt script-based cross-repo wrappers #133 is closed; de-tracking work is complete and rolled into this issue context

[anand-testcompare]

Investigation note (root-cause for root-level PNG files):

1. All diagram tools currently expose optional outputPath args (packages/opencode-excalidraw/src/index.ts).
2. If outputPath is provided, we call resolveOutputPath(args.outputPath, context.directory).
3. resolveOutputPath is currently just path.resolve(baseDir, path) (packages/opencode-excalidraw/src/lib/output.ts).
4. Therefore a bare filename like simple-excalidraw-diagram.png resolves to <repo-root>/simple-excalidraw-diagram.png.
5. The filenames seen in external-repo runs (e.g. simple-excalidraw-diagram.png, updated-*.png) indicate model-supplied outputPath values rather than plugin default path generation.
6. Existing tests only validate default-path behavior (no test where the model/tool call supplies outputPath), so this escaped coverage.

Proposed hard fix direction for implementation:

• Default output root: /.sketchi/sessions/<sessionID>/png/.
• Enforce containment: model/tool-provided outputPath cannot escape that root by default.
• Optional explicit escape hatch via env/config for power users.
• Auto-create /.sketchi/.gitignore so outputs are ignored even if root .gitignore is untouched.
• Add automated tests for model-provided outputPath (bare filename + traversal attempts) to ensure containment.

[anand-testcompare]

Status sweep after merged work (#128, #136, #138) as of 2026-02-20:\n\nCompleted:\n- Publishable package and release/publish automation landed in #128.\n- Package-first docs/page polish landed in #138.\n\nStill open in this issue:\n- Default artifact root is still sketchi/png (packages/opencode-excalidraw/src/lib/output.ts:5), not /.sketchi/sessions/<sessionID>/png.\n- Tool-provided outputPath is still unconstrained path resolve (packages/opencode-excalidraw/src/lib/output.ts:7-8).\n- Plugin still depends on centralized endpoints (packages/opencode-excalidraw/src/index.ts:55, :198, :355; packages/opencode-excalidraw/src/lib/api.ts:49).\n- Deterministic package-owned model defaults are not implemented in package code; current tracked agent file still sets model: opencode/kimi-k2.5-free and /sketchi output wording (.opencode/agents/sketchi-diagram.md:3, :20).\n\nRecommendation: keep #129 open as the parent until these remaining acceptance criteria are complete.

[anand-testcompare]

@shpit-agent clean this up. see #133

i'm not reading this unformatted historical narrative. ssummarize whats done, simplify whats remaining, and combine/merge issues where appropriate

[anand-testcompare]

Grooming pass complete: simplified the issue body to a done-vs-remaining view, removed stale narrative, and consolidated overlap with #133 (now closed). Keeping this open as the single tracker for remaining productization tasks.

[anand-testcompare]

Superseded by #184 for the release-flow/docs scope. Closing this noisy tracker to keep execution focused. Remaining unrelated productization work should be tracked separately as dedicated issues.