diff --git a/README.md b/README.md
index a82e359f15c..2cf4684e03b 100644
--- a/README.md
+++ b/README.md
@@ -131,10 +131,7 @@ Internally, the data for the export is generated by the
 `deployment.snapshot` getter:
 
 ```typescript
-assert.deepEqual(
-  Object.keys(deployment.snapshot.contracts),
-  ['kv1', 'kv2']
-)
+// TODO
 ```
 
 In a standard Fadroma project, where the Rust contracts
@@ -145,29 +142,7 @@ API client package, you can publish an up-to-date "address book"
 of your project's active contracts as part of your API client library.
 
 ```typescript
-// in your project's api.ts:
-
-import { Deployment } from '@fadroma/agent'
-
-// you would load snapshots as JSON, e.g.:
-// const testnet = await (await fetch('./testnet_v4.json')).json()
-export const mainnet = deployment.snapshot
-export const testnet = deployment.snapshot
-
-// and create instances of your deployment with preloaded
-// "address books" of contracts. for example here we restore
-// a different snapshot depending on whether we're passed a
-// mainnet or testnet connection.
-class DeploymentC extends Deployment {
-  kv1 = this.contract({ crate: 'examples/kv', name: 'kv1', initMsg: {} })
-  kv2 = this.contract({ crate: 'examples/kv', name: 'kv2', initMsg: {} })
-
-  static connect = (agent: Agent) => {
-    if (agent?.chain?.isMainnet) return new this({ ...mainnet, agent })
-    if (agent?.chain?.isTestnet) return new this({ ...testnet, agent })
-    return new this({ agent })
-  }
-}
+// TODO
 ```
 
 ### Connecting to an exported deployment
@@ -182,27 +157,13 @@ your project in mainnet or testnet mode, depending on
 what `Agent` you pass:
 
 ```typescript
-const mainnetAgent = { chain: { isMainnet: true } } // mock
-const testnetAgent = { chain: { isTestnet: true } } // mock
-
-const onMainnet = DeploymentC.connect(mainnetAgent)
-
-const onTestnet = DeploymentC.connect(testnetAgent)
-
-assert(onMainnet.isMainnet)
-assert(onTestnet.isTestnet)
-assert.deepEqual(Object.keys(onMainnet.contracts), ['kv1', 'kv2'])
-assert.deepEqual(Object.keys(onTestnet.contracts), ['kv1', 'kv2'])
+// TODO
 ```
 
 Or, to connect to individual contracts from the stored deployment:
 
 ```typescript
-const kv1 = DeploymentC.connect(mainnetAgent).kv1.expect()
-assert(kv1 instanceof Client)
-
-const kv2 = DeploymentC.connect(testnetAgent).kv2.expect()
-assert(kv2 instanceof Client)
+// TODO
 ```
 
 ### Adding custom migrations
@@ -211,22 +172,7 @@ Migrations can be implemented as static or regular methods
 of `Deployment` classes.
 
 ```typescript
-// in your project's api.ts:
-
-import { Deployment } from '@fadroma/agent'
-
-class DeploymentD extends DeploymentC {
-  kv3 = this.contract({ crate: 'examples/kv', name: 'kv3', initMsg: {} })
-
-  // simplest client-side migration is to just instantiate
-  // a new deployment with the data from the old deployment.
-  static upgrade = (previous: DeploymentC) =>
-    new this({ ...previous })
-}
-
-// simplest chain-side migration is to just call default deploy,
-// which should reuse kv1 and kv2 and only deploy kv3.
-deployment = await DeploymentD.upgrade(deployment).deploy()
+// TODO
 ```
 
 ## Template
@@ -245,40 +191,13 @@ an `address`.
 The `deployment.template` method adds a `Template` to the `Deployment`.
 
 ```typescript
-class Deployment4 extends Deployment {
-
-  t = this.template({ crate: 'examples/kv' })
-
-  a = this.t.instance({ name: 'a', initMsg: {} })
-
-  b = this.t.instances([
-    {name:'b1',initMsg:{}},
-    {name:'b2',initMsg:{}},
-    {name:'b3',initMsg:{}}
-  ])
-
-  c = this.t.instances({
-    c1:{name:'c1',initMsg:{}},
-    c2:{name:'c2',initMsg:{}},
-    c3:{name:'c3',initMsg:{}}
-  })
-
-}
+// TODO
 ```
 
 You can pass either an array or an object to `template.instances`.
 
 ```typescript
-deployment = await getDeployment(Deployment4).deploy()
-assert(deployment.t instanceof Template)
-
-assert([
-  deployment.a,
-  ...Object.values(deployment.b)
-  ...Object.values(deployment.c)
-].every(
-  c=>(c instanceof Contract) && (c.expect() instanceof Client)
-))
+// TODO
 ```
 
 ### Building from source code
@@ -288,22 +207,16 @@ When obtaining instances from a `Deployment`, the `builder` property
 is provided automatically from `deployment.builder`.
 
 ```typescript
-import { Builder } from '@fadroma/agent'
-assert(deployment.t.builder instanceof Builder)
-assert.equal(deployment.t.builder, deployment.builder)
+// TODO
 ```
 
 You can build a `Template` (or its subclass, `Contract`) by awaiting the
 `built` property or the return value of the `build()` method.
 
 ```typescript
-await deployment.t.built
-// -or-
-await deployment.t.build()
+// TODO
 ```
 
-See [the **build guide**](./build.html) for more info.
-
 ### Uploading binaries
 
 To upload, the `uploader` property must be set to a valid `Uploader`.
@@ -311,9 +224,7 @@ When obtaining instances from a `Deployment`, the `uploader` property
 is provided automatically from `deployment.uploader`.
 
 ```typescript
-import { Uploader } from '@fadroma/agent'
-assert(deployment.t.uploader instanceof Uploader)
-assert.equal(deployment.t.uploader, deployment.uploader)
+// TODO
 ```
 
 You can upload a `Template` (or its subclass, `Contract`) by awaiting the
@@ -323,13 +234,9 @@ If a WASM binary is not present (`template.artifact` is empty),
 but a source and a builder are present, this will also try to build the contract.
 
 ```typescript
-await deployment.t.uploaded
-// -or-
-await deployment.t.upload()
+// TODO
 ```
 
-See [the **upload guide**](./upload.html) for more info.
-
 ## Contract
 
 The `Contract` class describes an individual smart contract instance and uniquely identifies it
@@ -399,13 +306,7 @@ await deployment.a.built
 await deployment.a.build()
 ```
 
-```typescript
-import './Deploy.test.ts'
-```
-
----
-
-# Fadroma Guide: Devnet
+## Fadroma Guide: Devnet
 
 Fadroma enables fully local development of projects - no remote testnet needed!
 This feature is known as **Fadroma Devnet**. 
diff --git a/fadroma.test.ts b/fadroma.test.ts
index 3d49d04f976..5c9c8a7e960 100644
--- a/fadroma.test.ts
+++ b/fadroma.test.ts
@@ -76,9 +76,112 @@ export async function testProject () {
   await project.exportDeployment('state')
 }
 
-export async function testDeploy () {
-import { Deployment, Template, Contract, Client } from '@fadroma/agent'
-let deployment: Deployment
-let template:   Template
-let contract:   Contract
+export async function testDeployment () {
+assert.deepEqual(
+  Object.keys(deployment.snapshot.contracts),
+  ['kv1', 'kv2']
+)
+// in your project's api.ts:
+
+import { Deployment } from '@fadroma/agent'
+
+// you would load snapshots as JSON, e.g.:
+// const testnet = await (await fetch('./testnet_v4.json')).json()
+export const mainnet = deployment.snapshot
+export const testnet = deployment.snapshot
+
+// and create instances of your deployment with preloaded
+// "address books" of contracts. for example here we restore
+// a different snapshot depending on whether we're passed a
+// mainnet or testnet connection.
+class DeploymentC extends Deployment {
+  kv1 = this.contract({ crate: 'examples/kv', name: 'kv1', initMsg: {} })
+  kv2 = this.contract({ crate: 'examples/kv', name: 'kv2', initMsg: {} })
+
+  static connect = (agent: Agent) => {
+    if (agent?.chain?.isMainnet) return new this({ ...mainnet, agent })
+    if (agent?.chain?.isTestnet) return new this({ ...testnet, agent })
+    return new this({ agent })
+  }
+}
+const mainnetAgent = { chain: { isMainnet: true } } // mock
+const testnetAgent = { chain: { isTestnet: true } } // mock
+
+const onMainnet = DeploymentC.connect(mainnetAgent)
+
+const onTestnet = DeploymentC.connect(testnetAgent)
+
+assert(onMainnet.isMainnet)
+assert(onTestnet.isTestnet)
+assert.deepEqual(Object.keys(onMainnet.contracts), ['kv1', 'kv2'])
+assert.deepEqual(Object.keys(onTestnet.contracts), ['kv1', 'kv2'])
+
+const kv1 = DeploymentC.connect(mainnetAgent).kv1.expect()
+assert(kv1 instanceof Client)
+
+const kv2 = DeploymentC.connect(testnetAgent).kv2.expect()
+assert(kv2 instanceof Client)
+// in your project's api.ts:
+
+import { Deployment } from '@fadroma/agent'
+
+class DeploymentD extends DeploymentC {
+  kv3 = this.contract({ crate: 'examples/kv', name: 'kv3', initMsg: {} })
+
+  // simplest client-side migration is to just instantiate
+  // a new deployment with the data from the old deployment.
+  static upgrade = (previous: DeploymentC) =>
+    new this({ ...previous })
+}
+
+// simplest chain-side migration is to just call default deploy,
+// which should reuse kv1 and kv2 and only deploy kv3.
+deployment = await DeploymentD.upgrade(deployment).deploy()
+class Deployment4 extends Deployment {
+
+  t = this.template({ crate: 'examples/kv' })
+
+  a = this.t.instance({ name: 'a', initMsg: {} })
+
+  b = this.t.instances([
+    {name:'b1',initMsg:{}},
+    {name:'b2',initMsg:{}},
+    {name:'b3',initMsg:{}}
+  ])
+
+  c = this.t.instances({
+    c1:{name:'c1',initMsg:{}},
+    c2:{name:'c2',initMsg:{}},
+    c3:{name:'c3',initMsg:{}}
+  })
+
+}
+deployment = await getDeployment(Deployment4).deploy()
+assert(deployment.t instanceof Template)
+
+assert([
+  deployment.a,
+  ...Object.values(deployment.b)
+  ...Object.values(deployment.c)
+].every(
+  c=>(c instanceof Contract) && (c.expect() instanceof Client)
+))
+}
+
+export async function testBuild () {
+import { Builder } from '@fadroma/agent'
+assert(deployment.t.builder instanceof Builder)
+assert.equal(deployment.t.builder, deployment.builder)
+await deployment.t.built
+// -or-
+await deployment.t.build()
+}
+
+export async function testUpload () {
+import { Uploader } from '@fadroma/agent'
+assert(deployment.t.uploader instanceof Uploader)
+assert.equal(deployment.t.uploader, deployment.uploader)
+await deployment.t.uploaded
+// -or-
+await deployment.t.upload()
 }