update manual

Author: dsyme

README.md

@@ -1,21 +1,27 @@
 # Copilot Workspace User Manual
 
-Welcome! This is the user manual for Copilot Workspace, an experiment by GitHub Next.  Copilot Workspace is
-a Copilot-native development environment that allows you to collaborate with Copilot to solve coding tasks
-at the level of an entire repository.  You can learn more about what Copilot Workspace is at the [project page](https://githubnext.com/projects/copilot-workspace/).
+Welcome! This is the user manual for Copilot Workspace, an experiment by GitHub Next.  Copilot Workspace is a Copilot-native development environment that allows you to collaborate with Copilot to solve coding tasks at the level of an entire repository.  You can learn more about what Copilot Workspace is at the [project page](https://githubnext.com/projects/copilot-workspace/).
 
-This manual will help you understand how to use Copilot Workspace most effectively, and will share tips and tricks
-that we've learned while using Copilot Workspace to build Copilot Workspace.
+This manual will help you understand how to use Copilot Workspace most effectively, and will share tips and tricks that we've learned while using Copilot Workspace to build Copilot Workspace.
 
 ## Table of Contents
 
-* [Conceptual Overview](conceptual-overview.md)
+* [Overview](overview.md)
 * [Getting Started](getting-started.md)
 * [Tips and Tricks](tips-and-tricks.md)
+* [Terminal/Codespaces Guide](codespaces-guide.md)
+* Going Further
+  - [Creating Repositories](creating-repos.md)
+  - [Ad-hoc Tasks](adhoc-tasks.md)
+  - [Pull Request Tasks](pull-request-tasks.md)
+  - [Controls for Repository Maintainers](repo-maintainers.md)
+  - [Experiments, Roadmap and Known Issues](known-issues.md)
+  - [Further Techniques](further-techniques.md)
+  - [Responsible AI FAQ](responsible-ai-faq.md)
+  - [Origins](origins.md)
 
 ## Feedback
 
-To give general feedback, please join the [GitHub Next Discord](https://discord.gg/FeGshJZ2yy) and post in the #copilot-workspace channel.  Please provide a share link to the workspace and a description of the issue you're facing
-so that we can help you more effectively.
+To give general feedback, please join the [GitHub Next Discord](https://discord.gg/FeGshJZ2yy) and post in the #copilot-workspace channel.  Please provide a share link to the workspace and a description of the issue you're facing so that we can help you more effectively.
 
-To report harmful content, please email [email protected] with a description of the issue and a share link to the workspace.
+To report harmful content, please email [email protected] with a description of the issue and a share link to the workspace.

adhoc-tasks.md

@@ -0,0 +1,11 @@
+# Ad-hoc Tasks
+
+An ad-hoc task is a task that you define yourself, without the context of an issue or pull request. You can start an ad-hoc task from the Copilot Workspace dashboard, or from the repository page on GitHub.com.
+
+<img src="images/ad-hoc-task-full.png" width=400 alt="Panel on repository page to open an ad-hoc task in Copilot Workspace"><br>*Start an ad-hoc task in Copilot Workspace*
+
+Once started an ad-hoc task looks like this:
+
+<img src="images/adhoc-task-timeline-representation.png" width=600 alt="Ad-hoc task timeline representation"><br>*The timeline starts with the ad-hoc task and has no associated metadata*
+
+After creation, ad-hoc tasks proceed as for issue tasks.

codespaces-guide.md

@@ -0,0 +1,46 @@
+# Codespaces Starter Guide
+
+This document contains useful information for using the terminal/Codespace in your Workspace session.
+
+## Codespaces Limits
+
+### Overall Usage
+
+The technical preview includes limited free Codespaces compute usage that is reset at the start of the calendar month.
+
+### Overall Limits
+
+The technical preview enforces a total Codespaces and total active Codespaces limits that you may encounter. If closing Workspace sessions does not resolve these issues you may reach out to us [here](https://github.com/githubnext/copilot-workspace-user-manual?tab=readme-ov-file#feedback).
+
+### Organization based limits and policies
+If the Organization that owns the repository has set policies for Codespaces usage they will be applied to being able to create Codespaces for Workspace. You should reach out to an administrator of the organization to adjust any policies.
+
+## Common Errors
+
+#### You've reached your Copilot Workspace usage limit
+
+At the start of the next calendar month your free usage limit will reset and you can continue using Workspace. You may reach out to us and give us feedback about the usage limit [here](https://github.com/githubnext/copilot-workspace-user-manual?tab=readme-ov-file#feedback).
+
+#### Limit of active Copilot Workspace reached.
+
+Remediate this by closing open Workspace sessions and allowing previous sessions to shutdown before creating new ones.
+
+#### Limit of Copilot Workspace reached.
+Remediate this by closing open Workspace sessions and allowing previous sessions to shutdown before creating new ones.
+
+#### Repository may not be used for a Codespace
+
+This may be because of a repository or organization policy restricting Codespaces creation. Please check any settings in the organization or repository that may be preventing Codespaces usage. If you do not find any please reach out to our [technical
+preview feedback channels](https://github.com/githubnext/copilot-workspace-user-manual?tab=readme-ov-file#feedback) for assistance.
+
+#### The assigned location is currently unavailable.
+
+You may try again in a few minutes. Additionally, you can change your default Codespaces region in your user settings if you continue to run into this error for a particular region by following these [public docs](https://docs.github.com/en/codespaces/setting-your-user-preferences/setting-your-default-region-for-github-codespaces).
+
+#### Provided `devcontainer.json` cannot be parsed to valid JSON
+
+In the chosen repository you may need to fix the `devcontainer.json` for syntax errors. You can read more about `devcontainer.json` syntax in the following [public docs](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers).
+
+#### The organization has enabled OAuth App access restrictions, meaning that access to Copilot Workspace is limited.
+
+Reach out to the organization administrator to give access to the Copilot Workspace OAuth app.