docs: add an AI usage policy, AGENTS.md and CODEOWNERS

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-28 16:33:24 -03:00
parent d97b889455
commit 5ee037a7c3
7 changed files with 120 additions and 2 deletions
@@ -0,0 +1 @@
+* @nxtime
@@ -6,6 +6,10 @@

 <!-- Tests added, commands run, platforms tried. -->

+## AI assistance
+
+<!-- Which tool helped and how much, or "none". See AI_POLICY.md. You must understand every line. -->
+
 ## Screenshots

 <!-- For UI changes: before and after, at scale 2, in each theme. -->
@@ -17,3 +21,4 @@
 - [ ] Follows [RULES.md](../RULES.md) (no overflow, data safety, one undo step per tool call)
 - [ ] Docs, tool descriptions and `PROGRESS.md` updated where needed
 - [ ] Conventional commit messages
+- [ ] I read and understand every line of this change (AI-assisted or not)
@@ -0,0 +1,69 @@
+# Guidance for coding agents
+
+PaperCraft is a native Rust design and whiteboard canvas (egui, wgpu, winit) that AI agents drive
+over MCP and a CLI. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [RULES.md](RULES.md) first; this
+file is the short version for agents, and [AI_POLICY.md](AI_POLICY.md) says what the person using
+you is accountable for.
+
+## Commands
+
+```sh
+cargo build --release
+cargo fmt --all
+cargo clippy --all-targets
+cargo test --no-fail-fast                       # prefer one test: cargo test --test mcp name
+cargo check --lib --target wasm32-unknown-unknown
+```
+
+`tests/update.rs` cannot run on Windows (it needs elevation); that failure is known.
+
+## Running the app safely
+
+Never run a test copy against the person's real projects or MCP port, and never close or restart
+their running PaperCraft. Give yours its own folder and port, and keep its PID so you can stop only
+your own process:
+
+```sh
+PAPERCRAFT_HOME=/tmp/pc PAPERCRAFT_MCP_PORT=29998 ./target/release/papercraft
+```
+
+Do not stop processes by name.
+
+## Layout
+
+`src/model` (document), `src/editor` (tools and edits), `src/render` (wgpu), `src/mcp` (tools,
+HTML/CSS mapping, lint), `src/ui` (egui panels), `src/io` (import and export), `src/project`
+(store and formats), `tests/` (scenario tests), `specs/` (feature specs), `skills/` (agent
+skills). The README's project layout lists the rest.
+
+## Conventions
+
+* Tests first; match the style of the tests next to yours, and check the behaviour is not already
+  covered.
+* Changes to the document go through `Editor::edit`: one transaction, one undo step.
+* Handle errors; do not `unwrap` user data and do not discard errors with `let _ =`.
+* Comments explain *why*, never summarise the code. No dead code, debug prints or
+  commented-out blocks.
+* Files stay under about 800 lines; split by feature.
+* Reuse the shared UI kit and theme instead of one-off values. Nothing may overflow its container.
+* Writes to projects are atomic and format changes ship a migration (see RULES.md, "Data safety").
+* Adding or removing an MCP tool means a test in `tests/mcp.rs`, a precise description, and the
+  tool count updated in the README and ROADMAP.
+* Commits are conventional (`feat(scope): summary`) and focused. Do not commit, push or tag unless
+  the person asked you to.
+
+## Designing with PaperCraft (skills, examples, screenshots)
+
+* Themes are modes, never copies: one artboard per screen, a value per mode on each variable, and
+  `set_variable_mode` to switch. Never duplicate artboards for light and dark.
+* Every colour on a themed screen is a variable.
+* Check each artboard for overflow, programmatically and by screenshot in each mode, and run
+  `lint_design`.
+* Release design locks when you finish.
+
+## Avoid
+
+* Creative additions nobody asked for; stay inside the task.
+* Trivial tests, wide or optional types added to appease the compiler, and swallowed errors.
+* Editing generated files, lockfiles or release artifacts by hand, or touching files unrelated to
+  the task. Leave other people's uncommitted work alone.
@@ -0,0 +1,40 @@
+# AI usage policy
+
+PaperCraft is built to be driven by AI agents, and many of its contributors use them too. AI tools
+are welcome here. What we ask is that a person stays accountable for everything submitted.
+
+## For contributors
+
+* **You own what you submit.** Read every line of your pull request before asking for review. If
+  you cannot explain what a change does and how it fits the rest of the system without asking an
+  AI, do not submit it yet.
+* **Disclose meaningful AI help.** Say which tool you used and roughly how much it wrote in the
+  pull request description (for example "drafted with Claude Code, reviewed and tested by me").
+  Autocomplete and spell-checking do not need a note.
+* **Write issues yourself.** An agent can help you research, but the report should be in your own
+  words, trimmed to what matters, with reproduction steps you ran. Long generated text that nobody
+  checked puts the burden on maintainers.
+* **Think before you generate.** Agents jump to code and make their own job easy: trivial tests,
+  wide or optional types, swallowed errors, redundant comments, copied local patterns that do not
+  fit. Push back on all of it. [RULES.md](RULES.md) lists the standards to hold the output to.
+* **Verify.** Run the checks in [CONTRIBUTING.md](CONTRIBUTING.md), use the app, and attach
+  screenshots for UI changes. "The agent said it works" is not a test result.
+* **Answer automated review.** If a bot reviews your pull request, fix its findings or reply with
+  a one-line reason a finding does not apply.
+* **No bulk or drive-by pull requests.** Many small generated changes across the tree, or changes
+  to something nobody asked for, will be closed. Open an issue first for anything beyond a small
+  fix.
+
+Pull requests that clearly skip these steps may be closed without a detailed review. Repeated
+low-effort submissions can lead to a block, under the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## For coding agents
+
+Read [AGENTS.md](AGENTS.md). It holds the commands, conventions and guardrails an agent working in
+this repository should follow.
+
+## Why
+
+Every issue and pull request is read by a person. Review time is the scarce resource, and a change
+nobody understood costs more than it saves. AI that is reviewed, tested and understood by the
+person submitting it is a good way to build PaperCraft; AI used to skip that work is not.
@@ -0,0 +1 @@
+@AGENTS.md
@@ -5,7 +5,9 @@ first contribution is low: a typo fix, a clearer error message, a missing test o
 fix are all welcome.

 Please read [RULES.md](RULES.md) before writing code: it holds the standards a change is judged by.
-By taking part you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+By taking part you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). Using an AI tool is fine;
+the [AI usage policy](AI_POLICY.md) says what you stay responsible for, and coding agents should read
+[AGENTS.md](AGENTS.md).

 ## Ways to help

@@ -321,7 +321,7 @@ docs/                guides and screenshots

 ## Contributing

-Bug reports, ideas, docs and code are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) (setup, checks, commits, pull requests) and [RULES.md](RULES.md) (the standards a change is reviewed against). Security problems go through [SECURITY.md](SECURITY.md), and everyone follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+Bug reports, ideas, docs and code are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) (setup, checks, commits, pull requests) and [RULES.md](RULES.md) (the standards a change is reviewed against). AI tools are welcome under the [AI usage policy](AI_POLICY.md), and coding agents should read [AGENTS.md](AGENTS.md). Security problems go through [SECURITY.md](SECURITY.md), and everyone follows the [Code of Conduct](CODE_OF_CONDUCT.md).

 ## License and credits