feat(docs): move docs folder to the new documentation

apps/docs/src/pages/docs/_meta.json

@@ -1,7 +1,5 @@
 {
-  "-- Intro": {
-    "type": "separator",
-    "title": "Introduction"
-  },
-  "index": "Welcome"
+  "index": "Getting started",
+  "developers": "For contributors",
+  "adrs": "ADRs"
 }

docs/ci-cd.md → apps/docs/src/pages/docs/developers/ci-cd.md

@@ -15,7 +15,7 @@ directory will recursively run them in each app/package. The essential commands:
 ### Github actions
 
 All checks above will be run on opening a pull request and merging to main.
-Main merges will also deploy dapp on Firebase. Workflows can be [seen here](../.github/workflows).
+Main merges will also deploy dapp on Firebase. Workflows can be [seen here](../../../../../../.github/workflows).
 
 ### On release
 

docs/debugging.md → apps/docs/src/pages/docs/developers/debugging.md

@@ -2,7 +2,7 @@
 
 ### SCT Divergence
 
-Our [block processor](../packages/query/src/block-processor.ts) does the job of querying blocks and assembling
+Our [block processor](../../../../../../packages/query/src/block-processor.ts) does the job of querying blocks and assembling
 a filtered portion of the [state-commitment-tree](https://protocol.penumbra.zone/main/sct.html). This is
 then used for the user's transactions, on the client forming zk proofs that their commitment is included in this tree.
 If our code assembles this tree incorrectly (in wasm, in our database, in our block processor, etc). The user will
@@ -20,7 +20,7 @@ This is a programmer error, so we need to do a full audit of the surfaces that i
 - block processor
 
 To assist with this, we should validate the SCT root of each block to see where the divergence takes place.
-The `assertRootValid` function in our [block processor](../packages/query/src/block-processor.ts) can assist.
+The `assertRootValid` function in our [block processor](../../../../../../packages/query/src/block-processor.ts) can assist.
 This slows down block syncing significantly, so it's only used for debugging.
 
 Enable it by entering `globalThis.ASSERT_ROOT_VALID = true` in the service worker

docs/deployment.md → apps/docs/src/pages/docs/developers/deployment.md

@@ -15,7 +15,7 @@ As changes are made in the repo, devs are encouraged to generate a changeset via
 A very helpful description of the changes
 ```
 
-When we are ready to push these changes to NPM, run the [Packages Release](../.github/workflows/packages-release.yml) workflow.
+When we are ready to push these changes to NPM, run the [Packages Release](../../../../../../.github/workflows/packages-release.yml) workflow.
 If there are changesets, it will create a PR versioning the packages appropriately and adding changelogs.
 If there are no changesets, it will attempt to publish all packages with newer versions (not marked as private).
 

docs/guiding-principles.md → apps/docs/src/pages/docs/developers/guiding-principles.md

@@ -22,7 +22,7 @@ CI/CD pipeline `/.github/workflows` should actively enforce the best practices:
 - [Turborepo](https://turbo.build/) for builds
 
 It should not be possible to ship code that hasn't gone through the fire. Further, the use of `eslint` with quite high standards ([packages/eslint-config-custom/index.js](../packages/eslint-config-custom/index.js)) is necessary to keep the codebase
-code quality high. See [CI/CD guide](ci-cd.md) for running commands locally.
+code quality high. See [CI/CD guide](developers/ci-cd.mdrs/ci-cd.md) for running commands locally.
 
 ## Modularity from the beginning
 

docs/protobufs.md → apps/docs/src/pages/docs/developers/protobufs.md

@@ -23,4 +23,4 @@ It appears some fields that are required are listed as optional (e.g. noteCommit
 
 In short, you cannot trust the presence or absence of ANY fields in protobufs. Protos don't acknowledge how the application intends to use them and consumers are responsible for field validation.
 
-We do this via `Zod`. It's not everywhere, but hopefully it can be in most places! At runtime, we validate schemas using this library, forming the new, corrected type. [EXAMPLE](../packages/wasm/src/keys.ts)
+We do this via `Zod`. It's not everywhere, but hopefully it can be in most places! At runtime, we validate schemas using this library, forming the new, corrected type. [EXAMPLE](../../../../../../packages/wasm/src/keys.ts)

docs/testing.md → apps/docs/src/pages/docs/developers/testing.md

@@ -6,8 +6,8 @@ much as we can. If we do, our app will be far more resilient to changes.
 
 Different kinds of testing examples:
 
-- Unit tests: [packages/crypto/src/encryption.test.ts](../packages/crypto/src/encryption.test.ts)
-- Zod tests to validate types: [packages/wasm/src/client.test.ts](../packages/wasm/src/keys.test.ts)
+- Unit tests: [packages/crypto/src/encryption.test.ts](../../../../../../packages/crypto/src/encryption.test.ts)
+- Zod tests to validate types: [packages/wasm/src/client.test.ts](../../../../../../packages/wasm/src/keys.test.ts)
 
 ### Vitest
 

apps/docs/src/pages/docs/index.mdx

@@ -1 +1,82 @@
-# Welcome!
+import Image from 'next/image';
+
+# Docs
+
+## First read [Getting Started](https://github.com/penumbra-zone/web?tab=readme-ov-file#getting-started)
+
+These handy scripts may be executed directly in an app or package directory, in
+which case they only execute that package's script, or in the top level of the
+repo, in which case they use turbo or the monorepo configuration.
+
+- `pnpm clean`: remove build outputs.
+- `pnpm compile`: compile rust into wasm.
+- `pnpm build`: transform and bundle all packages and apps.
+- `pnpm dev`: build all, serve local apps. watch and rebuild continuously.
+- `pnpm test`: run vitest only. cargo tests are omitted.
+- `pnpm test:rust`: run cargo tests only.
+- `pnpm format`, `pnpm lint`
+- `pnpm all-check`: check all
+
+## Tools used
+
+- **pnpm**: a package manger
+  - pnpm's workspace feature is the foundation of the monorepo
+- **turborepo**: a monorepo scripting tool
+  - parallelize script execution
+  - manage execution dependency
+  - cache outputs to accelerate execution
+- **syncpack**: a monorepo dependency manager
+  - synchronize package dependencies
+  - validate dependency version ranges with configurable rules
+  - format and lint package json
+- **changeset**: a monorepo version manager
+  - increment semver in a topological way
+  - progressively compile release notes as PRs merge
+- **vite**: a bundler/dev server
+  - vite bundles monorepo apps for deployment
+  - vite's lib mode also builds and bundles some packages
+- **vitest**: a testing framework
+  - vitest is workspace-aware
+  - testing and bundling can use the same vite config
+  - vitest provides in-browser testing via playwright
+
+## The Basics
+
+### Local, compact chain state
+
+Minifront is a webapp blob which stores no state, and executes locally on the
+user's browser. Prax is a browser extension on the user's local machine, where
+it [manages keys](./custody.md), configuration, and [an abbreviated chain
+representing only the user's
+activity](https://www.youtube.com/watch?v=mHoe7lQMcxU).
+
+### Simplified architecture
+
+Minifront (and eventually other dapps) [connect to
+services](developers/extension-services.mdservices.md) hosted by Prax (and eventually other
+providers) for information on the user's chain state, and to conduct new
+activity.
+
+Prax queries a remote 'full node' `pd` endpoint to scan the compact chain,
+download full block details when interested, and broadcast new chain activity.
+Omitting the remote endpoint, it looks something like this:
+
+![Penumbra Web Architecture](/penumbra-web-architecture.svg)
+
+### Some critical details
+
+Prax and Minifront [share React components](developers/ui-library.md-library.md) and some other
+reuseable dependencies.
+
+Both Prax and Minifront manage running state with Zustand. For storage, Prax
+uses extension storage and idb. Minifront does not store anything.
+
+Prax [parallelizes WASM during transaction
+builds](https://penumbra.zone/blog/faster-client-side-proving-with-parallelism)
+by launching individual [web workers](./web-workers.md) for each chunk of work.
+Chrome extension workers can't launch web workers, so this is managed via the
+'Offscreen' feature of the chrome extension API which provides full DOM
+compatibility.
+
+WASM directly accesses IDB for some operations, outside of the typical
+interface.