1 Commits

Include renames

Author	SHA1	Message	Date
DottaandPaperclip	e9bc2efdaa	docs: turn DeepWiki into a contributor handbook (#13745) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Contributors need to understand its control plane and find the code that owns each behavior. > - The public DeepWiki has many pages, but it lacks a guided path through task execution and system boundaries. > - A refresh alone cannot define that reading path or the evidence each page must show. > - This pull request adds a 30-page contributor handbook configuration with source anchors and clear page boundaries. > - The handbook helps contributors trace work, investigate failures, and choose the right code and tests. ## Linked Issues or Issue Description **Issue type** Unclear or confusing documentation; outdated generated documentation. **Where is the issue?** [Paperclip DeepWiki](https://deepwiki.com/paperclipai/paperclip). The repository did not have a `.devin/wiki.json` configuration. **What's wrong?** The wiki needs a contributor reading path. Readers need to connect product terms to implementation, follow a task through both execution paths, and find the state and tests that explain failures. Index freshness also depends on regeneration. **Suggested fix** Define six chapters and 30 pages in `.devin/wiki.json`. Give each page source anchors, required questions, and coverage boundaries. Use shared notes for evidence standards, diagrams, terminology, and freshness rules. Keep existing generation effort settings. Searched public issues and PRs for DeepWiki, wiki, and contributor handbook work. No duplicate or related DeepWiki change was found. Checked `ROADMAP.md`; this is a documentation configuration change. ## What Changed - Add only `.devin/wiki.json`, using the [documented DeepWiki configuration](https://docs.devin.ai/work-with-devin/deepwiki#steering-deepwiki). - Define 30 pages under Understand Paperclip, Contribute to Paperclip, Orchestrate Work, Run Agents, Extend and Integrate, and Govern and Diagnose. - Add 68 generation notes with 244 verified repository source paths. Require source and test citations, useful parent pages, and explicit ownership boundaries. - Require a task tour with separate direct-adapter and experimental Runner paths, run and task state diagrams, and a connection authorization flow. - Separate run logs, operator-configured observability, and first-party telemetry. Require defaults and feature gates to be resolved from the indexed code. ## Verification - Passed JSON and supported-field validation. Checked unique titles, valid parents, an acyclic hierarchy, the exact page tree, note limits, and all 244 source paths. - Reviewed coverage against the six reader questions in the plan. Confirmed each page has source anchors, test anchors, and coverage boundaries. - Passed `git diff --check`. - Passed `pnpm -r typecheck` and `pnpm build` on the implementation base, `c65fc9e3c81c41aafe421aa90a00514b84343285`. - Ran `pnpm test:run`. The broad run hit a 15-second timeout in `server/src/services/native-runtime/remote-deliverable-file.test.ts`, in “reads verified remote bytes without touching controller paths”. Stopped the broad run after the failure. Full-suite verification remains incomplete. - Reran that test file in isolation: all 30 tests passed in 6.45 seconds. - Rebased onto current `master`, `57fd8b70d`. Repeated configuration, source-path, and diff validation after the rebase. No application tests were added for this configuration-only change. - After merge, request DeepWiki regeneration. Confirm its indexed commit contains the configuration. Then check the generated task tour and one page from each chapter against implementation and test citations. Regeneration and generated-page review are pending. ## Risks - Generated text can still contain errors. The instructions require citations and honest treatment of conflicting evidence, but the generated pages need review. - The new page structure can change navigation and page links. - Source paths and implementation can change between generations. Notes require replacement anchors, current defaults, and clear labels for experimental behavior. - The public index stays stale until someone requests regeneration. This PR adds no refresh service and changes no application behavior. ## Model Used OpenAI Codex, based on GPT-6. The exact runtime model identifier, context window size, and reasoning setting are not exposed in this session. Used repository inspection, web research, shell tools, and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-09-21 10:04:43 -05:00