paritytech · tjjfvi · Mar 9, 2023 · Mar 8, 2023 · Mar 8, 2023 · Mar 8, 2023
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -60,8 +60,8 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-<admin@parity.io>.
-All complaints will be reviewed and investigated promptly and fairly.
+<admin@parity.io>. All complaints will be reviewed and investigated promptly and
+fairly.
 
 All community leaders are obligated to respect the privacy and security of the
 reporter of any incident.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,30 +1,41 @@
 # Contributing
 
-When contributing to this repository, please check our open issues and whether there is already an issue related to your idea. Please first discuss the change you wish to make in a GitHub issue and wait for a reply from the maintainers of this repository before making a change.
+When contributing to this repository, please check our open issues and whether
+there is already an issue related to your idea. Please first discuss the change
+you wish to make in a GitHub issue and wait for a reply from the maintainers of
+this repository before making a change.
 
-We have a [code of conduct](CODE_OF_CONDUCT.md); please follow it in all your interactions relating to the project.
+We have a [code of conduct](CODE_OF_CONDUCT.md); please follow it in all your
+interactions relating to the project.
 
 ## Environment setup
 
 ### Container environment setup
 
-Develop locally using the [VSCode Remote Container](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension and [Docker](https://docs.docker.com/get-docker/). [![Open in Remote - Containers](https://img.shields.io/badge/Remote_--_Container-Open-blue?logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/paritytech/capi)
+Develop locally using the
+[VSCode Remote Container](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+extension and [Docker](https://docs.docker.com/get-docker/).
+[![Open in Remote - Containers](https://img.shields.io/badge/Remote_--_Container-Open-blue?logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/paritytech/capi)
 
 ### Local environment setup
 
-To develop on your machine, install the following (and please submit issues if errors crop up)
+To develop on your machine, install the following (and please submit issues if
+errors crop up)
 
 - [Deno](https://deno.land/manual@v1.19.3/getting_started/installation)
 - [Docker](https://docs.docker.com/get-docker/)
-- [NodeJS](https://nodejs.org/) (only necessary if you're going to run [the dnt task](./_/tasks/dnt.ts))
+- [NodeJS](https://nodejs.org/) (only necessary if you're going to run
+  [the dnt task](./_/tasks/dnt.ts))
 - [dprint](https://dprint.dev/)
 
 ## Rules
 
 There are a few basic ground-rules for contributors:
 
-1. **All modifications** must be made in a **pull-request** to solicit feedback from other contributors
-2. Contributors should attempt to adhere to the prevailing [code-style](#code-style)
+1. **All modifications** must be made in a **pull-request** to solicit feedback
+   from other contributors
+2. Contributors should attempt to adhere to the prevailing
+   [code-style](#code-style)
 
 ## Pull requests
 
@@ -34,47 +45,61 @@ There are a few basic ground-rules for contributors:
 
 :white_check_mark: &nbsp; Have one approving review
 
-:white_check_mark: &nbsp; Have the PR title follow [conventional commit](https://www.conventionalcommits.org/)
+:white_check_mark: &nbsp; Have the PR title follow
+[conventional commit](https://www.conventionalcommits.org/)
 
 **Ideally, a good pull request should:**
 
 :clock3: &nbsp; Take less than 15 minutes to review
 
-:open_book: &nbsp; Have a meaningful description (describes the problem being solved)
+:open_book: &nbsp; Have a meaningful description (describes the problem being
+solved)
 
-:one: &nbsp; Introduce one feature or solve one bug at a time, for which an open issue already exists. In case of a project wide refactoring, a larger PR is to be expected, but the reviewer should be more carefully guided through it
+:one: &nbsp; Introduce one feature or solve one bug at a time, for which an open
+issue already exists. In case of a project wide refactoring, a larger PR is to
+be expected, but the reviewer should be more carefully guided through it
 
-:jigsaw: &nbsp; Issues that seem too big for a PR that can be reviewed in 15 minutes or PRs that need to touch other issues should be discussed and probably split differently before starting any development
+:jigsaw: &nbsp; Issues that seem too big for a PR that can be reviewed in 15
+minutes or PRs that need to touch other issues should be discussed and probably
+split differently before starting any development
 
-:dart: &nbsp; Handle renaming, moving files, linting and formatting separately (not alongside features or bug fixes)
+:dart: &nbsp; Handle renaming, moving files, linting and formatting separately
+(not alongside features or bug fixes)
 
 :test_tube: &nbsp; Add tests for new functionality
 
-**Draft pull requests for early feedback are welcome and do not need to adhere to any guidelines.**
+**Draft pull requests for early feedback are welcome and do not need to adhere
+to any guidelines.**
 
-When reviewing a pull request, the end-goal is to suggest useful changes to the author. Reviews should finish with approval unless there are issues that would result in:
+When reviewing a pull request, the end-goal is to suggest useful changes to the
+author. Reviews should finish with approval unless there are issues that would
+result in:
 
 :x: &nbsp; Buggy behavior
 
 :x: &nbsp; Undue maintenance burden
 
 :x: &nbsp; Measurable performance issues
 
-:x: &nbsp; Feature reduction (i.e. it removes some aspect of functionality that a significant minority of users rely on)
+:x: &nbsp; Feature reduction (i.e. it removes some aspect of functionality that
+a significant minority of users rely on)
 
-:x: &nbsp; Uselessness (i.e. it does not strictly add a feature or fix a known issue)
+:x: &nbsp; Uselessness (i.e. it does not strictly add a feature or fix a known
+issue)
 
 :x: &nbsp; Disabling a compiler feature to introduce code that wouldn't compile
 
 ## Code style
 
-We use the following tools to enforce linting rules, formatting and spell checking
+We use the following tools to enforce linting rules, formatting and spell
+checking
 
 - [`deno lint`](https://deno.land/manual/tools/linter)
 - [`dprint`](https://dprint.dev/)
 - [`cspell`](https://cspell.org/)
 
-We encourage adding the [recommended](.vscode/extensions.json) (or similar) extensions to your IDE.
+We encourage adding the [recommended](.vscode/extensions.json) (or similar)
+extensions to your IDE.
 
 To run a project wide check you can use:
 
@@ -90,15 +115,20 @@ Declaring formal releases remains the prerogative of the project maintainer(s).
 
 ## License
 
-By contributing to project, you agree that your contributions will be licensed under its [Apache license](LICENSE).
+By contributing to project, you agree that your contributions will be licensed
+under its [Apache license](LICENSE).
 
 ## Changes to this arrangement
 
-This is an experiment and feedback is welcome! This document may also be subject to pull-requests or changes by contributors where you believe you have something valuable to add or change.
+This is an experiment and feedback is welcome! This document may also be subject
+to pull-requests or changes by contributors where you believe you have something
+valuable to add or change.
 
 ## Heritage
 
 These contributing guidelines are modified from
 
-- the "Substrate Project" guidelines https://github.com/paritytech/substrate/blob/master/docs/CONTRIBUTING.adoc
-- the "Substrate Contracts UI" guidelines https://github.com/paritytech/contracts-ui/blob/master/CONTRIBUTING.md
+- the "Substrate Project" guidelines
+  https://github.com/paritytech/substrate/blob/master/docs/CONTRIBUTING.adoc
+- the "Substrate Contracts UI" guidelines
+  https://github.com/paritytech/contracts-ui/blob/master/CONTRIBUTING.md
diff --git a/Readme.md b/Readme.md
@@ -1,77 +1,86 @@
 # Capi
 
-> Capi is a work in progress. The documentation may not reflect the current implementation. **Expect a stable release and proper documentation in early 2023**.
+> Capi is a work in progress. The documentation may not reflect the current
+> implementation. **Expect a stable release and proper documentation in early
+> 2023**.
 
-Capi is a declarative, TypeScript-first toolkit for crafting interactions with Substrate-based chains. It consists of [FRAME](https://docs.substrate.io/reference/glossary/#frame) utilities, a functional effect system (Rune) and a fluent API, which facilitates multistep, multichain interactions without compromising either performance or safety.
+Capi is a framework for crafting interactions with Substrate chains. It consists
+of a development server and fluent API, which facilitates multistep, multichain
+interactions without compromising either performance or ease of use.
 
+- [Docs &rarr;](https://docs.capi.dev)<br />Guides for Capi developers and
+  pattern library developers
 - [Examples &rarr;](./examples)<br />SHOW ME THE CODE
-- [API Reference &rarr;](https://deno.land/x/capi/mod.ts)<br />A generated API reference, based on type signatures and in-source comments.
-- [Type Conversion Guide &rarr;](./docs/Types.md)<br />Guide for Capi's conversion of types from Rust to TypeScript
+- [API Reference &rarr;](https://deno.land/x/capi/mod.ts)<br />A generated API
+  reference, based on type signatures and TSDocs.
 
 ## At a Glance
 
-Run the local server.
-
-```sh
-deno run -A https://deno.land/x/capi/main.ts
-```
-
-Then, open your IDE and import pallet-corresponding modules from the local server.
-
-```ts
-import { System } from "http://localhost:4646/frame/wss/rpc.polkadot.io/@latest/mod.ts"
-
-const key = System.Account.keys().first()
-
-const value = System.Account.entry(key)
-
-console.log(await value.run())
-```
-
-### Import Mapping
-
-For simplicity, we recommend aliasing import specifiers via import maps.
+Create an import map with the specifier corresponding to your target.
 
 `import_map.json`
 
 ```json
 {
   "imports": {
-    "#polkadot/": "http://localhost:4646/frame/wss/rpc.polkadot.io/@latest/"
+    "@capi/polkadot/": "https://capi.dev/frame/wss/rpc.polkadot.io/@latest/"
   }
 }
 ```
 
-```diff
-- import { System } from "http://localhost:4646/frame/wss/rpc.polkadot.io/@latest/mod.ts"
-+ import { System } from "#polkadot/mod.ts"
+Then, open your editor and import from the mapped chain module.
+
+```ts
+import { System } from "@capi/polkadot/mod.ts"
+
+const key = System.Account
+  .keyPage(1)
+  .access(0)
+  .unhandle(undefined)
+
+const value = System.Account.value(key)
+
+console.log(await value.run())
 ```
 
-## Examples
+## Running Examples
 
-See [the `examples/` directory](./examples).
+Within a fresh clone of the repository...
+
+<!-- TODO: track https://github.com/denoland/dotland/issues/2650#issuecomment-1437015262 -->
 
 ```sh
-git clone https://github.com/partitytech/capi
-cd capi
-deno task run codegen # host the server locally and cache all codegen
-deno task run examples/<example-name>.ts
+deno task run examples/<example_name>.ts
 ```
 
-## The Thesis
+## Rationale
 
-In a likely future of specialized, interoperable chains, developers will need to make use of on-chain programs to satisfy varying use cases; the expertise required to interact with these on-chain programs is currently greater than that which _should_ be expected of app developers. Does this mean that app developers must forgo integrating with this blossoming infrastructure? We think not; **the open source community can use Capi to abstract over the atomics of the on-chain world**. An interaction spanning several chains and dozens of methods can be described with a single effect.
+In a likely future of specialized, interoperable chains, developers will need to
+make use of on-chain programs to satisfy varying use cases; the expertise
+required to interact with these on-chain programs is currently greater than that
+which _should_ be expected of app developers. Does this mean that app developers
+must forgo integrating with this blossoming infrastructure? We think not; **the
+open source community can use Capi to abstract over the atomics of the on-chain
+world**. An interaction spanning several chains and dozens of methods can be
+described with a single Rune[^1].
 
-As you read through this documentation, please consider use cases over which you might like to abstract; if you wish to add your use case to [Capi's standard library](effects), please [submit an issue](https://github.com/paritytech/capi/issues/new).
+As you read through this documentation, please consider use cases over which you
+might like to abstract; if you wish to add your use case to
+[Capi's standard library](patterns), please
+[submit an issue](https://github.com/paritytech/capi/issues/new?title=pattern%20idea:%20).
 
 ## Code of Conduct
 
-Everyone interacting in this repo is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+Everyone interacting in this repo is expected to follow the
+[code of conduct](CODE_OF_CONDUCT.md).
 
 ## Contributing
 
-Contributions are welcome and appreciated! Check out the [contributing guide](CONTRIBUTING.md) before you dive in.
+Contributions are welcome and appreciated! Check out the
+[contributing guide](CONTRIBUTING.md) before you dive in.
 
 ## License
 
 Capi is [Apache licensed](LICENSE).
+
+[^1]: Rune is the unit of composition with which we model Capi programs.