diff --git a/source/docs/async-parsing.md b/source/docs/async-parsing.md
index b0a5bc3..897812c 100644
--- a/source/docs/async-parsing.md
+++ b/source/docs/async-parsing.md
@@ -10,7 +10,7 @@ The API of sywac can be logically separated into two stages of an app’s lifecy
This page covers the two `Api` methods designed for the execution stage.
-## `.parse(args)`
+## `.parse(args, state)`
Since 1.0.0
@@ -24,6 +24,10 @@ Note that this method is safe to use concurrently, meaning it is suitable for se
The arguments or message to parse, validate, and execute.
+- `state`: optional user-defined state object
+
+ Rarely used, helpful for passing per-request data to concurrent parse requests. Any state you pass here will be attached to the [context](/docs/context.html).
+
Returns a `Promise` that resolves to a result object, containing the following properties:
- `code`: number/integer
@@ -95,7 +99,7 @@ sywac.parse(msg).then(result => {
```
-## `.parseAndExit(args)`
+## `.parseAndExit(args, state)`
Since 1.0.0
@@ -111,6 +115,10 @@ Note that in a command-driven app, it may be perfectly reasonable to call this m
The arguments or message to parse, validate, and execute.
+- `state`: optional user-defined state object
+
+ Rarely used, included for feature parity with `parse`. Any state you pass here will be attached to the [context](/docs/context.html).
+
Returns a `Promise` that resolves to the `argv` object (subproperty of detailed results) representing the parsed arguments and options as key-value pairs, where each key is a configured alias of an argument/option and each value is the parsed/coerced value for that argument/option. See further description in the [parse method](#parse).
Example:
diff --git a/source/docs/context.md b/source/docs/context.md
index 9e3e192..3bf3274 100644
--- a/source/docs/context.md
+++ b/source/docs/context.md
@@ -5,6 +5,43 @@ next: /docs/advanced-customizations.html
---
# Context
-> No content yet
->
-> Sorry! This site is still under construction. Please bear with us until we can fill out more documentation. Thank you!
+The context is a short-lived object that tracks state during asynchronous parsing, validation, and execution. It is created when the user initiates a [parse](/docs/async-parsing.html#parse) or [parseAndExit](/docs/async-parsing.html#parseAndExit) request, and is discarded when the request finishes.
+
+The user usually interacts with the context by defining callbacks:
+
+- The [check](/docs/sync-config.html#check) handler receives the context as a parameter.
+- A [command](/docs/sync-config.html#command)'s run handler receives the context as a parameter.
+
+
+## `.cliMessage(msg)`
+
+Since 1.0.0 {
+ context.cliMessage('Oops, you forgot to enter your name.')
+})
+```
+
+
+## `.state`
+
+Since FUTURE
+
+A user-defined state object. This object exists only if passed as a second argument to [parse](/docs/async-parsing.html#parse).
+
+Example:
+
+```js
+sywac.command('login', {
+ run: (argv, context) => {
+ console.log(`Thank you for logging in, ${context.state.user.name}!`)
+ }
+})
+
+sywac.parse('login', { user: { name: 'jan.jansen' } })
+```