Imported from Suckholee/matdaho (AGENTS.md). Install upstream with npx skills add Suckholee/matdaho. Copyright stays with the author.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

Matdaho agent guidelines

Matdaho is a personal-productivity agent application. Any implementation must preserve the following product contracts.

Operating principles

• Treat every user-facing action as a proposed, reviewable action. The agent may prepare outputs and drafts, but must obtain explicit user approval before an external side effect.
• Use the canonical ontology identifiers and schemas defined in TRD.md. Free-form input is normalized into those identifiers; business logic must not depend directly on model-generated labels.
• Keep model providers interchangeable. Provider-specific prompts, responses, costs, and failures belong behind an adapter; application services consume a shared typed contract.
• Retain provenance for every generated artifact: source records, ontology version, template version, model, prompt version, evaluation result, and user feedback.
• Do not use private user content for cross-user training or evaluation unless the user has separately and explicitly opted in.
• Keep the required agent handoff explicit: Microsoft Agent Framework normalizes and evaluates; GitHub Copilot SDK generates the user-facing artifact from the normalized contract. Do not replace either stage with a mock or client-side model call.
• Keep all agent SDK calls and provider credentials server-side. Validate cross-service payloads and return classified errors without exposing raw provider responses.

Feedback-loop requirements

• Separate generation from evaluation. An evaluator must receive the candidate, the structured task context, and a rubric, not the generator's self-reported confidence alone.
• Record feedback as structured signals (accepted, edited, rejected, rating, and optional reason codes). Do not infer a positive outcome from delivery alone.
• Make selection deterministic for the same eligible candidates, scoring configuration, and tie-breaker inputs. Store the score breakdown.
• Keep human approval and policy checks outside model prompts and enforce them server-side.

Workspace interaction requirements

• The center document editor is the source of truth for an active draft. Drive, Output, Chat, and History are directional surfaces over that document, not independent editors.
• Preserve unsaved drafts when opening or closing a directional surface. Apply generated output, chat suggestions, and restored history only through explicit, reversible commands that create a new revision.
• Scope Drive and Chat context to source references the user explicitly selected and is authorized to access. Show that context in the UI.
• Treat the Output surface as a review surface: display provenance, assumptions, and approval state with the final result.
• Preserve keyboard access and focus flow for all directional controls; arrows alone must never be the only affordance or accessible label.

Delivery checklist

• Update PRD.md when user-visible behavior, scope, success metrics, or product decisions change.
• Update TRD.md when schemas, ontology terms, template rules, model contracts, or feedback processing change.
• Add automated coverage for deterministic normalization, selection, policy, and feedback aggregation whenever those behaviors are implemented or changed.
• Maintain a public Azure guest/demo path that exercises the core workflow without exposing user data or requiring reviewer credentials.