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

..

wiki.json

docs: turn DeepWiki into a contributor handbook (#13745)

2026-09-21 10:04:43 -05:00