chore: create mkdocs for goose

.gitignore

@@ -20,12 +20,10 @@ parts/
 sdist/
 var/
 wheels/
-pip-wheel-metadata/
 share/python-wheels/
 *.egg-info/
 .installed.cfg
 *.egg
-MANIFEST
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -49,7 +47,6 @@ coverage.xml
 *.cover
 *.py,cover
 .hypothesis/
-.pytest_cache/
 
 # Translations
 *.mo
@@ -58,8 +55,6 @@ coverage.xml
 # Django stuff:
 *.log
 local_settings.py
-db.sqlite3
-db.sqlite3-journal
 
 # Flask stuff:
 instance/
@@ -68,7 +63,11 @@ instance/
 # Scrapy stuff:
 .scrapy
 
+# Sphinx documentation
+docs/_build/
+
 # PyBuilder
+.pybuilder/
 target/
 
 # Jupyter Notebook
@@ -88,7 +87,8 @@ ipython_config.py
 #   install all needed dependencies.
 #Pipfile.lock
 
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
 __pypackages__/
 
 # Celery stuff
@@ -100,12 +100,8 @@ celerybeat.pid
 
 # Environments
 .env
+.env.*
 .venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
 
 # Spyder project settings
 .spyderproject
@@ -114,30 +110,15 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# Ignore mkdocs site files generated locally for testing/validation, but generated
-# at buildtime in production
-site/
-docs/docs/notebooks*
+# mkdocs documentation
+/site
 
 # mypy
 .mypy_cache/
 .dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# Hermit
-.hermit
 
 # VSCode
 .vscode
 
 # Autogenerated docs files
-docs/docs/reference
-
-## goose session files
-.goose
-
-# ignore lockfile
-uv.lock
+docs/docs/reference

CONTRIBUTING.md

@@ -1,18 +1,46 @@
 # Contributing
 
-We welcome Pull Requests for general contributions. If you have a larger new feature or any questions on how
-to develop a fix, we recommend you open an issue before starting.
+<p align="center">
+<a href="#prerequisites">Prerequisites</a> •
+<a href="#evaluations">Evaluations</a> •
+<a href="#developing-and-testing">Developing and testing</a> •
+<a href="#building-from-source">Building from source</a> •
+<a href="#developing-goose-plugins">Developing goose-plugins</a> •
+<a href="#running-ai-exchange-from-source">Running ai-exchange from source</a> •
+<a href="#evaluations">Evaluations</a> •
+<a href="#build-a-toolkit">Build a Toolkit</a> •
+<a href="#conventional-commits">Conventional Commits</a>
+</p>
+
+We welcome Pull Requests for general contributions. If you have a larger new feature or any questions on how to develop a fix, we recommend you open an [issue][issues] before starting.
 
 ## Prerequisites
 
 We provide a shortcut to standard commands using [just][just] in our `justfile`.
 
-* *goose* uses [uv][uv] for dependency management, and formats with [ruff][ruff] - install UV first: https://pypi.org/project/uv/ 
+Goose uses [uv][uv] for dependency management, and formats with [ruff][ruff] - install UV first: https://pypi.org/project/uv/ 
 
 ## Developing and testing
 
 Now that you have a local environment, you can make edits and run our tests. 
 
+### Creating plugins
+
+Goose is highly configurable through plugins - it reads in modules that its dependencies install (e.g.`goose-plugins`) and uses those that start with certain prefixes (e.g. `goose.toolkit`) to inject their functionality. For example, you will note that Goose's CLI is actually merged with additional CLI methods that are exported from `goose-plugins`.
+
+If you are building a net new feature, you should try to fit it inside a plugin. Goose and `goose-plugins` both support plugins, but there's an important difference in how contributions to each are reviewed. Use the guidelines below to decide where to contribute:
+
+**When to Add to Goose:**
+
+* Higher Scrutiny: Plugins added directly to Goose are subject to more rigorous and detailed reviews. This is because these plugins are considered part of Goose's core system and need to meet higher standards for stability, performance, and maintainability.
+* Core or Essential Plugins: If the plugin is critical to Goose's functionality or tightly coupled to its internal architecture, it should be added to Goose.
+
+**When to Add to Goose-Plugins:**
+
+* Lighter Scrutiny: Plugins in goose-plugins undergo less thorough reviews compared to Goose. This repository is intended for more modular, optional, or experimental plugins that may not be critical to Goose’s core functionality.
+* General, Reusable Plugins: If the plugin could be useful in a variety of contexts or is designed to extend Goose in a more optional way, it belongs in goose-plugins. This allows for faster iteration and easier contributions.
+
+### Running tests
 ```sh
 uv run pytest tests -m "not integration"
 ```
@@ -23,39 +51,63 @@ or, as a shortcut,
 just test
 ```
 
-## Running goose from source
+## Building from source
 
-`uv run goose session start`
+If you want to develop features on `goose`:
 
-will run a fresh goose session (can use the usual goose commands with `uv run` prefixed)
+1. Clone Goose:
+ ```bash
+ git clone [email protected]:square/goose.git ~/Development/goose
+ ```
+2. Get `uv` with `brew install uv`
+3. Set up your Python virtualenv:
+```bash
+cd ~/Development/goose
+uv sync
+uv venv
+```
+4. Run the `source` command that follows the `uv venv` command to activate the virtualenv.
+5. Run Goose:
+```bash
+uv run goose session start  # or any of goose's commands (e.g. goose --help)
+```
+
+## Developing goose-plugins
+
+1. Clone the `goose-plugins` repo:
+```bash
+ git clone [email protected]:square/goose-plugins.git ~/Development/goose-plugins
+```
+2. Follow the steps for creating a virtualenv in the `goose` section above
+3. Install `goose-plugins` in `goose`. This means any changes to `goose-plugins` in this folder will immediately be reflected in `goose`:
+```bash
+uv add --editable ~/Development/goose-plugins
+```
+4. Make your changes in `goose-plugins`, add the toolkit to the `profiles.yaml` file and run `uv run goose session --start` to see them in action.
 
 ## Running ai-exchange from source
 
-goose depends heavily on the https://github.com/square/exchange project, you can clone that repo and then work on both by running: 
+goose depends heavily on the [`ai-exchange`][ai-exchange] project, you can clone that repo and then work on both by running: 
 
 ```sh
 uv add --editable <path/to/cloned/exchange>
+```
 
-then when you run goose with `uv run goose` it will be running it all from source. 
+then when you run goose with `uv run goose session start` it will be running it all from source. 
 
 ## Evaluations
 
-Given that so much of *goose* involves interactions with LLMs, our unit tests only go so far to
-confirming things work as intended.
+Given that so much of Goose involves interactions with LLMs, our unit tests only go so far to confirming things work as intended.
 
-We're currently developing a suite of evalutions, to make it easier to make improvements to *goose* more confidently.
+We're currently developing a suite of evaluations, to make it easier to make improvements to Goose more confidently.
 
-In the meantime, we typically incubate any new additions that change the behavior of the *goose*
-through **opt-in** plugins - `Toolkit`s, `Moderator`s, and `Provider`s. We welcome contributions of plugins 
-that add new capabilities to *goose*. We recommend sending in several examples of the new capabilities 
-in action with your pull request.
+In the meantime, we typically incubate any new additions that change the behavior of the Goose through **opt-in** plugins - `Toolkit`s, `Moderator`s, and `Provider`s. We welcome contributions of plugins that add new capabilities to *goose*. We recommend sending in several examples of the new capabilities in action with your pull request.
 
 Additions to the [developer toolkit][developer] change the core performance, and so will need to be measured carefully.
 
 ## Build a Toolkit
 
-To add a toolkit, start out with a plugin as mentioned above. In your code (which doesn't necessarily need to be
-in the goose package thanks to [plugin metadata][plugin]!), create a class that derives from Toolkit.
+To add a toolkit, start out with a plugin as mentioned above. In your code (which doesn't necessarily need to be in the goose package thanks to [plugin metadata][plugin]!), create a class that derives from Toolkit.
 
 ```python
 import os
@@ -134,6 +186,9 @@ goose session start --profile demo
 
 This project follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for PR titles. Conventional Commits make it easier to understand the history of a project and facilitate automation around versioning and changelog generation.
 
+[issues]: https://github.com/square/goose/issues
+[goose-plugins]: https://github.com/square/goose-plugins
+[ai-exchange]: https://github.com/square/exchange
 [developer]: src/goose/toolkit/developer.py
 [uv]: https://docs.astral.sh/uv/
 [ruff]: https://docs.astral.sh/ruff/