Doc updates

.devcontainer/devcontainer.json

@@ -9,12 +9,13 @@
                 "terminal.integrated.shell.linux": "/bin/bash"
             },
             "extensions": [
-                "salesforce.salesforcedx-vscode",
-                "CumulusCI.cci",
-                "GitHub.copilot",
-                "robocorp.robotframework-lsp",
-                "ms-python.python"
-            ]
+				"salesforce.salesforcedx-vscode",
+				"CumulusCI.cci",
+				"GitHub.copilot",
+				"robocorp.robotframework-lsp",
+				"ms-python.python",
+				"GitHub.copilot-chat"
+			]
         }
     },
     "remoteEnv": {

docs/index.md

@@ -1,46 +1,34 @@
-# Welcome to MuseLab D2X
+# Introducing D2X
 
-MuseLab D2X is an open source collection of processes and tools that make it easy implement and operate a comprehensive Development to Delivery Experience (D2X) for reusable and composable Salesforce products and services.
+D2X is an open source collection of tools and configurations to quickly launch and easily maintain Salesforce development projects on GitHub. D2X combines the best of CumulusCI, Salesforce CLI, GitHub Actions, and GitHub Codespaces. D2X projects are set up to align with the Salesforce Well-Architected principle of [Adaptable (Resilient and Composable)](https://architect.salesforce.com/well-architected/adaptable/overview).
 
-D2X combines the best of CumulusCI, Salesforce CLI, GitHub Actions, and GitHub Codespaces.
+D2X is made up of:
 
-All D2X projects start off with batteries included such as:
+* A Docker image with the latest versions of CumulusCI and SF CLI preinstalled
+
+  * GitHub Package: https://github.com/muselab-d2x/d2x/pkgs/container/d2x
+  * Latest Docker Image: `ghcr.io/muselab-d2x/d2x:latest`
+
+* A set of [reusable GitHub Actions workflows](https://github.com/muselab-d2x/d2x/tree/main/.github/workflows)
+* A [devcontainer](https://containers.dev) [configuration](https://github.com/muselab-d2x/d2x/tree/main/.devcontainer) for use with GitHub Codespaces or any IDE with a Devcontainers extension
+* A [project template](https://github.com/muselab-d2x/d2x-template) using [cookiecutter](https://cookiecutter.readthedocs.io)
 
-* CumulusCI & Salesforce DX project configuration
-* GitHub Actions CI/CD Builds
-  * Feature Test
-  * Beta Release/Test
-  * Production Release
-* Pre-configured Devcontainer ready to use with GitHub Codespaces or the VS Code Devcontainers extension to provide a consistent, fully configured runtime environments to everyone working on the project and build 
-* Reduced maintainance via the ghcr.io/muselab-d2x/d2x:latest Docker image used throughout the lifecycle and maintained by MuseLab
 
 ## Starting a D2X Project
 
 The easiest way to get started is with the D2X Launchpad application which provides a simple web interface to launching new GitHub repositories fully configured for D2X:
 [https://launchpad.muselab.com]
 
-### Using with an existing GitHub repository
-TBD
-
-## Using a D2X Project
-
-D2X provides a consistent developer experience across all D2X projects.
-
-### Launching a development environment
-
-We recommend using GitHub Codespaces as development environments for greater productivity, reduced developer tooling support burden, and security. Codespaces provides on-demand, web based VS Code instances. D2X provides a customized Codespaces image that includes all the right tooling versions and configurations.
-
-To launch a Codespace, simply click Code then select the Codespaces tab on the GitHub repository's main page.
+## Post-Launch Tutorial
 
-#### Setting up DEV_HUB_AUTH_URL
+You've created your own GitHub repository using [D2X Launchpad](https://launchpad.muselab.com), now what?
 
-Your Codespaces need access to your DevHub to create scratch orgs. You can configure the DEV_HUB_AUTH_URL secret on your GitHub account to provide all your Codespaces with access to the DevHub automatically. This is a one-time setup operation for all your Codespaces.
+Head over to the [D2X Project Tutorial](tutorial.md) for next steps on finalizing your project's setup and getting started building.
 
-To start, you need to get the sfdxAuthUrl for your DevHub. To do this, you can use sfdx either on your computer or via Codespaces.
+## References
 
-** via Codespaces **
-If you don't already have sfdx installed on your computer and connected to your DevHub, you can use a Codespace to connect to the DevHub so you can get the sfdxAuthUrl. Simply launch a new Codespace from your D2X project repository then run:
-`sfdx org login device --set-default-dev-hub --alias DevHub`
+D2X itself doesn't require a lot of documentation. It's really about stitching together some amazingly powerful tools. Learning those tools is an important part of learning to work with D2X. The following documentation provides resouces to learn about those tools:
 
-** via sfdx **
-Assuming you already have sfdx installed on your computer and connected to your DevHub as the alias `DevHub`, you should be able to get the Sfdx Auth Url (starts with force://) by running `sfdx org display -o DevHub --verbose` andy copying the auth url (starts with force://, ends with .salesforce.com)
+* [CumulusCI Documentation](https://cumulusci.readthedocs.io)
+* [Trailhead: Build Applications with CumulusCI](https://trailhead.salesforce.com/content/learn/trails/build-applications-with-cumulusci)
+* [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli)

docs/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs==1.5.2
+mkdocs_material==9.2.8

docs/tutorial.md

@@ -0,0 +1,99 @@
+# D2X Project Tutorial
+
+This tutorial assumes you've already created a D2X project repository on GitHub. If you haven't yet done that, please refer to the documentation on [Starting a D2X Project](index.md#starting-a-d2x-project).
+
+## DevHub and Packaging Org
+
+You will need access to a [Salesforce org with DevHub enabled](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_setup_enable_devhub.htm) to run [GitHub Actions](https://docs.github.com/en/actions) builds and create scratch orgs in [GitHub Codespaces](https://docs.github.com/en/codespaces/overview).
+
+For the DevHub, it is possible to use the [Limited Access - Free](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/dev_hub_license.htm?q=limited%20access) license for the user you use in Actions and Codespaces.
+
+If you specified a namespace prefix, you will need to make sure the namespace is [registered with your DevHub](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_unlocked_pkg_create_namespace.htm?q=namespace).
+
+If you created a 1GP Managed project, you will also need admin access to a packaging org, a [Salesforce Developer Edition org with the package's namespace prefix registered](https://developer.salesforce.com/docs/atlas.en-us.pkg1_dev.meta/pkg1_dev/register_namespace_prefix.htm).
+
+### Getting an SfdxAuthUrl for an Org
+
+To do this, you can use sfdx either on your computer or via Codespaces.
+
+**via Codespaces** If you don't already have sfdx installed on your computer and connected to your DevHub, you can [use a Codespace](#launching-a-development-environment) to connect to the DevHub so you can get the sfdxAuthUrl. Simply launch a new Codespace from your D2X project repository then run: sfdx org login device --set-default-dev-hub --alias DevHub
+
+**via sfdx** Assuming you already have sfdx installed on your computer and connected to your DevHub as the alias DevHub, you should be able to get the Sfdx Auth Url (starts with force://) by running sfdx org display -o DevHub --verbose andy copying the auth url (starts with force://, ends with .salesforce.com)
+
+## GitHub Token
+
+GitHub Actions and GitHub Codespaces both generate a default API token that's limited to the current repository. D2X projects can support dependencies on other D2X project repositories via [CumulusCI's Dependency Management](https://cumulusci.readthedocs.io/en/stable/dev.html#manage-dependencies). The challenge is that the default GitHub Actions and GitHub Codespaces tokens don't have access to any other repositories for CumulusCI Dependency Management to work.
+
+The solution is to [generate a GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) and set it as the value for the `CCI_GITHUB_TOKEN` secret.
+
+## Secrets
+
+Finishing your project's configuration requires setting [GitHub Actions Secrets for the repository or organization]() and [GitHub Codespaces Secrets for your user or the organization](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-secrets-for-your-repository-and-organization-for-github-codespaces#recommended-secrets-for-a-repository).
+
+The following secrets need to be set in all projects:
+
+* `DEV_HUB_AUTH_URL`: The [SfdxAuthUrl providing access to the DevHub](#devhub-and-packaging-org)
+
+Projects with dependencies need set:
+
+* `CCI_GITHUB_TOKEN`: The [GitHub Personal Access Token providing access to repositories](#github-token)
+
+1GP Managed projects need to set:
+
+* `PACKAGING_ORG_AUTH_URL`: The [SfdxAuthUrl proving access to the packaging org](#devhub-and-packaging-org)
+
+
+
+## Develop
+
+### Launching a development environment
+
+We recommend using GitHub Codespaces as development environments for greater productivity, reduced developer tooling support burden, and security. Codespaces provides on-demand, web based VS Code instances. D2X provides a customized Codespaces image that includes all the right tooling versions and configurations.
+
+To launch a Codespace, simply click Code then select the Codespaces tab on the GitHub repository's main page.
+
+You can also use any [IDE that support the devcontainer specification](https://containers.dev/supporting).
+
+### Creating your first scratch org
+
+Assuming you have all your secrets set up correctly, you should be able to run the following command in the terminal:
+
+```
+cci flow run dev_org
+```
+
+If there are errors, you'll likely want to double check the GitHub Codespace Secrets.
+
+### Open the scratch org
+
+Open up the scratch org in a browser and make some metadata changes like adding a field:
+
+```
+cci org browser
+```
+
+### Capture your changes
+
+List changes from the scratch org:
+```
+cci task run list_changes
+```
+
+Filter down the list to remove any metadata you don't want:
+```
+cci task run list_changes --exclude Profile:,Layout:
+```
+
+Retrieve the changes:
+```
+cci task run retrieve_changes --exclude Profile:,Layout:
+```
+
+### Commit the changes
+
+
+### Commit your changes
+
+# Merge
+
+# Release

mkdocs.yml

@@ -1 +1,5 @@
-site_name: MuseLab D2X Documentation
+site_name: D2X Documentation
+theme:
+  name: material
+extra_css:
+  - stylesheets/extra.css