diff --git a/expressions/README.md b/expressions/README.md
index b2a15ad..2076ada 100644
--- a/expressions/README.md
+++ b/expressions/README.md
@@ -1,6 +1,6 @@
-# actions-expressions
+# actions/expressions
 
-`actions-expressions` is a library to parse and evaluate GitHub Actions [expressions](https://docs.github.com/actions/learn-github-actions/expressions).
+`@actions/expressions` is a library to parse and evaluate GitHub Actions [expressions](https://docs.github.com/actions/learn-github-actions/expressions).
 
 ## Installation
 
diff --git a/languageserver/README.md b/languageserver/README.md
index 9c0cbf3..6698e5c 100644
--- a/languageserver/README.md
+++ b/languageserver/README.md
@@ -1,4 +1,4 @@
-# actions-languageserver
+# actions/languageserver
 
 `actions-languageserver` hosts the `actions-languageservice` and makes it available via the [language server protocol](https://microsoft.github.io/language-server-protocol/) (LSP) as a standalone language server.
 
diff --git a/languageservice/README.md b/languageservice/README.md
index f853365..76a6072 100644
--- a/languageservice/README.md
+++ b/languageservice/README.md
@@ -1,4 +1,4 @@
-# actions-languageservice
+# actions/languageservice
 
 This package contains the logic for the GitHub Actions workflows language server.
 
@@ -22,14 +22,6 @@ The language service features use three sources of information:
 * _value providers_ which can dynamically add values to the schema, for example, the list of available labels for a repository when validating `runs-on`.
 * _context providers_ which can dynamically provide available contexts used in [expressions](https://docs.github.com/actions/reference/context-and-expression-syntax-for-github-actions#about-contexts-and-expressions). For example, the contents of the `github.event` context for a given workflow file.
 
-##### Value Providers
-
-TODO
-
-##### Context Providers
-
-TODO
-
 #### Validation
 
 Validate a workflow file, returns an array of [`Diagnostic`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnostic) objects.
@@ -60,7 +52,43 @@ const hover = await hover(document, {line: 0, character: 1}); // { contents: { k
 
 #### Auto-completion
 
-TODO
+```typescript
+import {complete} from "@actions/languageservice";
+
+const document = {
+  uri: "file:///path/to/file",
+  getText: () => `on: 
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - run: echo hello`
+};
+
+// Trigger completion for `on: |`
+const suggestions = await complete(document, {line: 0, character: 4});
+```
+
+will return
+
+```jsonc
+[{
+  "documentation": {
+    "kind": "markdown",
+    "value": "Runs your workflow when branch protection rules in the workflow repository are changed.",
+  },
+  "label": "branch_protection_rule",
+  "textEdit": {
+    "newText": "branch_protection_rule",
+    "range": {
+      "end": {"character": 4, "line": 0,},
+      "start": {"character": 4, "line": 0},
+    },
+  },
+},
+//... other events
+]
+```
 
 ## Contributing
 
diff --git a/workflow-parser/README.md b/workflow-parser/README.md
new file mode 100644
index 0000000..e480668
--- /dev/null
+++ b/workflow-parser/README.md
@@ -0,0 +1,87 @@
+# actions/workflow-parser
+
+`@actions/workflow-parser` is a library to parse GitHub Actions [workflows](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions).
+
+## Installation
+
+The [package](https://www.npmjs.com/package/@actions/workflow-parser) contains TypeScript types and compiled ECMAScript modules.
+
+```bash
+npm install @actions/workflow-parser
+```
+
+## Usage
+
+The parser is driven by a custom schema defined in [`worflows-v1.0.json`](./src/workflow-v1.0.json).
+
+### Simple example
+
+`parseWorkflow` parses the workflow YAML into an intermediate representation and validates that it conforms to the schema. Any parsing errors are returned in the `errors` property of the result context.
+
+```typescript
+var trace: TraceWriter;
+
+const result = parseWorkflow(
+  {
+    name: "test.yaml",
+    content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - run: echo 'hello'`
+  },
+  trace
+);
+```
+
+`convertWorkflowTemplate` then takes that intermediate representation and converts it to a [`WorkflowTemplate`](./src/workflow-template.ts) object, which is a more convenient representation for working with workflows.
+
+```typescript
+const workflowTemplate = await convertWorkflowTemplate(result.context, result.value);
+
+// workflowTemplate.jobs[0].id === "build"
+// workflowTemplate.jobs[0].steps[0].run === "echo 'hello'"
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository for general guidelines and recommendations.
+
+Similar to [`actions/expressions](../expressions/), this project is just one of multiple implementations of the GitHub Actions workflow parser. We therefore cannot accept contributions that significantly modify the schema or the overall behavior of the parser. If you would like to propose changes to Actions itself, please use our [Community Forum](https://github.com/community/community/discussions/categories/actions-and-packages).
+
+If you do want to contribute, please run [prettier](https://prettier.io/) to format your code and add unit tests as appropriate before submitting your PR. [./testdata](./testdata) contains test cases that all implementations should pass, please also make sure those tests are still passing.
+
+### Build
+
+```bash
+npm run build
+```
+
+or to watch for changes
+
+```bash
+npm run watch
+```
+
+### Test
+
+```bash
+npm test
+```
+
+or to watch for changes and run tests:
+
+```bash
+npm run test-watch
+```
+
+### Lint
+
+```bash
+npm run format-check
+```
+
+## License
+
+This project is licensed under the terms of the MIT open source license. Please refer to [MIT](../LICENSE) for the full terms.