Created
March 1, 2026 01:25
-
-
Save denniswon/06ce7fed8a9b4dbd6749636391e51557 to your computer and use it in GitHub Desktop.
newton dev docs revamp roadmap
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| ⏺ Phase 1 (.claude/ infrastructure) is complete. The original plan mentioned the next phases would cover the documentation revamp — new | |
| pages, restructuring, FAQ/Glossary, etc. | |
| I don’t have a detailed plan written for Phase 2. What would you like to tackle next? Some options: | |
| 1. Restructure the Developers tab — reorganize into the planned Getting Started → Guides → Concepts → Reference → Advanced → Resources | |
| structure | |
| 2. Add new pages — FAQ, Glossary, or other missing content | |
| 3. Content audit — review existing pages for accuracy, broken links, outdated info | |
| 4. Something else — if you have a specific plan doc or priorities in mind | |
| Do you have a Phase 2 plan ready, or should we start by scoping it? | |
| ❯ We first need to do a full research and audit of our current documentation. Put yourself in the perspective of a new developer | |
| who just got introduced/got interested with first impression as a potential solution to integrate. @~/projects/foundation-docs/ | |
| is the Developer documentation website for external | |
| developers to efficiently build on Newton Protocol (both smart contract integration for their NewtonPolicyClient extended | |
| contracts, | |
| and offchain integration for developing, testing their policies, policy data, policy clients, etc. and submit task requests to | |
| get | |
| policies evaluated for their policy clients. Note that @~/projects/newton-prover-avs is the core protocol codebase, and | |
| @~/projects/newton-dashboard-api/ is the developer dashboard backend api that serves the dashboard frontend where the external | |
| developers would create their API keys, verify the ownership of their Policy Cilents, develop/test policies with policy data, | |
| etc., | |
| and they use that same API key for submitting task requests etc. to newton-prover-gateway in @~/projects/newton-prover-avs. The | |
| current documentation, this repo, is currently built using Mintlify platform https://www.mintlify.com/docs. This documentation | |
| contains ALL information regarding how to develop/update/edit/etc. for the developer documentation website. The current | |
| developer | |
| documentation is FAR from being good enough, it is still too difficult in my opinion. Cross-referencing newton-prover-avs, | |
| newton-dashboard-api, and this repo foundation-docs, we will revamp the current developer documentation from the FIRST | |
| PRINCIPLE, | |
| and our goal is that just from the developer documentation website, any devs (depending on their level of familiarity with web3 | |
| blockchain concepts or level of technical understanding, the guides should be sectioned to intro/quickstart/advanced, etc.). | |
| Also, | |
| the guide should start with clear information about what Newton Protocol is, why it exists, what is it good for/tangible use | |
| cases, | |
| examples, the high level architectural/flow overview to give them high level understanding of the process happening underneath, | |
| security, design choices, privacy, etc. Also, we should be clear about different trade offs for different options for | |
| developers to | |
| take when there are multiple paths/approaches etc. Lastly, it should have FAQ section at the end, and also Glossary that | |
| explains | |
| blockchain-related or specialized knoweldge/jargons/concepts, etc. with pointers for readers to learn more. Note that | |
| @~/projects/newton-prover-avs/docs/ contains a number of documentations that could be useful as you explore and execute. | |
| ⎿ Listed directory / | |
| ⎿ Listed directory ../newton-prover-avs/ | |
| ⎿ Listed directory ../newton-dashboard-api/ | |
| ⎿ Listed directory ../newton-prover-avs/docs/ | |
| ⏺ Skill(oh-my-claudecode:research) | |
| ⎿ Successfully loaded skill | |
| ⏺ I’ll decompose this into 5 parallel research stages covering all three repos. Let me fire off the scientist agents. | |
| ⏺ 5 agents finished (ctrl+o to expand) | |
| ├─ oh-my-claudecode:scientist (Audit foundation-docs content) · 37 tool uses · 146.7k tokens | |
| │ ⎿ Done | |
| ├─ oh-my-claudecode:scientist (Audit newton-prover-avs docs) · 32 tool uses · 42.3k tokens | |
| │ ⎿ Done | |
| ├─ oh-my-claudecode:scientist (Audit dashboard API docs) · 44 tool uses · 116.9k tokens | |
| │ ⎿ Done | |
| ├─ oh-my-claudecode:scientist-high (Map new developer journey) · 22 tool uses · 105.2k tokens | |
| │ ⎿ Done | |
| └─ oh-my-claudecode:scientist (Cross-repo gap analysis) · 28 tool uses · 121.8k tokens | |
| ⎿ Done | |
| ⏺ All 5 research stages are complete. Let me synthesize the findings. | |
| --- | |
| Documentation Audit — Synthesis Report | |
| Executive Summary | |
| The current documentation has strong reference content (RPC API: 5/5, Policy Client Guide: 5/5, Whitepaper: 5/5) but critically fails | |
| at developer onboarding. A new developer faces three showstoppers before writing a single line of code. | |
| --- | |
| 3 Showstoppers (P0) | |
| ┌─────┬─────────────────────────────────────────────────────────────────────────────────────────────┬─────────────────────────────┐ | |
| │ # │ Problem │ Impact │ | |
| ├─────┼─────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────┤ | |
| │ 1 │ No real quickstart — the “Quickstart” page delegates everything to an AI assistant. Zero │ Developers who don’t use │ | |
| │ │ manual code path. │ Claude/Cursor are stranded │ | |
| ├─────┼─────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────┤ | |
| │ │ API keys gated behind email — 4 separate pages say “email product@magicnewton.com”. The │ Developers abandon at 11pm │ | |
| │ 2 │ Dashboard API has 35 live endpoints including self-service key creation (SIWE + Email OTP) │ on a Saturday │ | |
| │ │ but none are documented. │ │ | |
| ├─────┼─────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────┤ | |
| │ │ KMS encryption undocumented — newt_storeEncryptedSecrets requires encrypting with “Newton’s │ Any PolicyData using │ | |
| │ 3 │ KMS key” but no ARN, no region, no code example │ external API keys is │ | |
| │ │ │ blocked │ | |
| └─────┴─────────────────────────────────────────────────────────────────────────────────────────────┴─────────────────────────────┘ | |
| --- | |
| 4 Critical Factual Errors | |
| ┌─────┬────────────────────────────────────────────────────────────────────────┬──────────────────────────────────────────────────┐ | |
| │ # │ Error │ Source of Truth │ | |
| ├─────┼────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤ | |
| │ 1 │ Ownership model described as DB-based/permanent — actually on-chain │ newton-prover-avs/docs/RPC_API.md, CHANGELOG │ | |
| │ │ via getOwner() since v0.2.0 │ │ | |
| ├─────┼────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤ | |
| │ 2 │ CLI reference missing 7 of 8 policy-client subcommands (only │ newton-prover-avs/docs/CHANGELOG.md v0.2.0 │ | |
| │ │ set-policy-params documented) │ │ | |
| ├─────┼────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤ | |
| │ 3 │ SDK example uses chainId: 1 (mainnet) — not a supported chain │ SDK reference page itself lists only │ | |
| │ │ │ Sepolia/Base Sepolia │ | |
| ├─────┼────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤ | |
| │ 4 │ newt_getPrivacyPublicKey and newt_uploadEncryptedData exist in │ newton-prover-avs/docs/PRIVACY.md (678 lines) │ | |
| │ │ production — completely undocumented │ │ | |
| └─────┴────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────┘ | |
| --- | |
| Structural Problems | |
| ┌─────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────┐ | |
| │ Problem │ Details │ | |
| ├─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ Monolithic integration guide │ ~1,200 lines covering 5 technology domains (WASM, Rego, CLI, Solidity, Next.js) in one page │ | |
| ├─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ Policy Client Guide misplaced │ The most important Solidity integration page is hidden in “Advanced” — intermediate devs skip │ | |
| │ │ it │ | |
| ├─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ No Concepts page │ Newton’s mental model (Policy→Intent→Task→Attestation) is scattered across 4 different pages │ | |
| ├─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ No Glossary │ Newton-specific terms used before being defined; no standalone reference │ | |
| ├─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ No FAQ/Troubleshooting │ Only the Policy Client Guide has a troubleshooting section │ | |
| ├─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ Single Guide page │ The “Guides” nav section contains exactly 1 page │ | |
| ├─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ building-policies is a stub │ 87 lines, placeholder frontmatter (“Description of your new file.“) │ | |
| ├─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ Rego guide is generic │ Doesn’t explain Newton-specific input/data.params/data.data namespaces or Newton crypto │ | |
| │ │ builtins │ | |
| ├─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ WASM→Rego data flow │ No page explains how run() output becomes data.data in Rego │ | |
| │ undocumented │ │ | |
| └─────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────┘ | |
| --- | |
| Content Gap Analysis | |
| Completely Missing Pages | |
| ┌─────────────────────────────────────────────────────┬──────────┬────────────────────────────────────────────────────────┐ | |
| │ Missing Page │ Priority │ Source Material │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ Dashboard API reference (auth, API keys, ownership) │ P0 │ newton-dashboard-api/ — 35 endpoints, all undocumented │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ Concepts / Mental Model page │ P0 │ Scattered across about.mdx + policy-client-guide.mdx │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ Real Quickstart (minimal “hello world”) │ P0 │ Needs to be written from scratch │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ Privacy Layer guide │ P1 │ newton-prover-avs/docs/PRIVACY.md (678 lines) │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ Contract Addresses reference table │ P1 │ newton-prover-avs/docs/OPERATOR.md + SDK source │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ Glossary │ P1 │ Content style guide has the terms │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ FAQ / Troubleshooting │ P1 │ Policy Client Guide has partial content │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ Testing & Debugging guide │ P1 │ newt_simulateTask, newt_simulatePolicy, regorus eval │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ Deployment Checklist │ P1 │ Needs to be written │ | |
| ├─────────────────────────────────────────────────────┼──────────┼────────────────────────────────────────────────────────┤ | |
| │ Error Reference (consolidated) │ P2 │ SDK reference + RPC API both have partial error tables │ | |
| └─────────────────────────────────────────────────────┴──────────┴────────────────────────────────────────────────────────┘ | |
| Undocumented from Source Repos | |
| ┌──────────────────────────────────────────────────────┬────────────────────────────────────────┬─────────────────┐ | |
| │ Content │ Source │ Public Coverage │ | |
| ├──────────────────────────────────────────────────────┼────────────────────────────────────────┼─────────────────┤ | |
| │ Privacy Layer (HPKE, SecureEnvelope, dual-signature) │ PRIVACY.md │ 0% │ | |
| ├──────────────────────────────────────────────────────┼────────────────────────────────────────┼─────────────────┤ | |
| │ Two-Phase Consensus mechanics │ CONSENSUS.md │ 5% │ | |
| ├──────────────────────────────────────────────────────┼────────────────────────────────────────┼─────────────────┤ | |
| │ Multichain / destination chains │ MULTICHAIN.md + CROSS_CHAIN_GATEWAY.md │ 10% │ | |
| ├──────────────────────────────────────────────────────┼────────────────────────────────────────┼─────────────────┤ | |
| │ Rego crypto extensions (newton.crypto.*) │ REGORUS.md │ 0% │ | |
| ├──────────────────────────────────────────────────────┼────────────────────────────────────────┼─────────────────┤ | |
| │ newton-cli regorus eval subcommand │ REGORUS.md │ 0% │ | |
| ├──────────────────────────────────────────────────────┼────────────────────────────────────────┼─────────────────┤ | |
| │ newton-cli version info/check-compatibility/migrate │ VERSIONING.md │ 0% │ | |
| ├──────────────────────────────────────────────────────┼────────────────────────────────────────┼─────────────────┤ | |
| │ Operator registration workflow │ OPERATOR.md │ 0% │ | |
| ├──────────────────────────────────────────────────────┼────────────────────────────────────────┼─────────────────┤ | |
| │ Dashboard SIWE auth + self-service API key flow │ Dashboard API routes │ 0% │ | |
| └──────────────────────────────────────────────────────┴────────────────────────────────────────┴─────────────────┘ | |
| --- | |
| Page Quality Ratings | |
| ┌────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ | |
| │ Rating │ Pages │ | |
| ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ 5/5 │ rpc-api, policy-client-guide, all 10 whitepaper pages │ | |
| ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ 4/5 │ about, integration-guide, sdk-reference, python-wasm, rust-wasm │ | |
| ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ 3/5 │ newton-explorer, command-line-tool, context-file, rego-syntax-guide, policy-data-oracles, javascript-wasm, bug-bounty, │ | |
| │ │ foundation pages, token pages │ | |
| ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ | |
| │ 2/5 │ quickstart, building-policies, project-and-protocol, transparency-reports, governance-model │ | |
| └────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ | |
| --- | |
| Recommended New Structure | |
| Developers Tab (revamped) | |
| ├── Getting Started | |
| │ ├── What is Newton? ← rewrite of about.mdx (shorter, with code teaser) | |
| │ ├── Core Concepts ← NEW: mental model, diagrams, term definitions | |
| │ ├── Quickstart ← NEW: minimal hello-world with existing policy | |
| │ └── Dashboard & API Keys ← NEW: self-service key creation via Dashboard API | |
| │ | |
| ├── Guides | |
| │ ├── Writing Data Oracles ← extracted from integration-guide | |
| │ ├── Writing Rego Policies ← extracted from integration-guide + building-policies rewrite | |
| │ ├── Deploying with CLI ← extracted from integration-guide | |
| │ ├── Smart Contract Integration (PolicyClient) ← promoted from Advanced | |
| │ └── Frontend SDK Integration ← extracted from integration-guide | |
| │ | |
| ├── Concepts | |
| │ ├── Architecture Overview ← expanded from about.mdx architecture section | |
| │ ├── Privacy Layer ← NEW from PRIVACY.md | |
| │ ├── Consensus & Security ← NEW from CONSENSUS.md | |
| │ └── Multichain Support ← NEW from MULTICHAIN.md | |
| │ | |
| ├── Reference | |
| │ ├── SDK Reference ← existing (fix errors) | |
| │ ├── RPC API ← existing (fix ownership model, add privacy methods) | |
| │ ├── CLI Reference ← existing (add missing 7 subcommands) | |
| │ ├── Contract Addresses ← NEW | |
| │ ├── Dashboard API ← NEW | |
| │ ├── Error Reference ← NEW (consolidated) | |
| │ └── Glossary ← NEW | |
| │ | |
| ├── Advanced | |
| │ ├── Rego Syntax (Newton-specific) ← rewrite with Newton namespaces + crypto builtins | |
| │ ├── WASM Oracles (JS/Python/Rust) ← existing (add http.fetch examples) | |
| │ ├── Policy Data Catalog ← existing | |
| │ └── KMS Encryption Guide ← NEW | |
| │ | |
| └── Resources | |
| ├── FAQ & Troubleshooting ← NEW | |
| ├── Deployment Checklist ← NEW | |
| ├── Testing & Debugging ← NEW | |
| ├── Newton Explorer ← existing | |
| └── LLM Context Files ← moved from Reference | |
| --- | |
| This gives us a clear roadmap. |
Author
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
❯ Also, note that We should not mention anything about AWS KMS which is just a temporary solution until the Newton Privacy Layer is
in place and productionized (currently in active development). We should just introduce the core concepts for the Newton Privacy
Layer and for the developer guides for using Privacy Layer (which currently is being served in the centralized way using AWS KMS
solution), unless the AWS KMS encryption/decryption is "abstracted" out via the developer newton-sdk or API, we should indicate
that this is currently in active development and for more information, contact us via email (same email for api key support).
High level, Newton Protocol should remain as the decentralized protocol throughout the protocol (which is why we don't want to
mention that protocol uses / relies on AWS KMS for privacy).