conda-workspaces 0.1.0__tar.gz

conda_workspaces-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/docs.yml"
+      - "conda_workspaces/**"
+      - "docs/**"
+      - "pyproject.toml"
+  pull_request:
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@82d477f15f3a381dbcc8adc1206ce643fe110fb7 # v0.9.3
+        with:
+          environments: docs
+      - name: Build docs
+        run: pixi run -e docs docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: "docs/_build/dirhtml"
+
+  pages:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs: [docs]
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

conda_workspaces-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+
+      - name: Build sdist and wheel
+        run: pipx run build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build]
+    environment: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          packages-dir: dist/
+
+  upload-release-assets:
+    name: Upload release assets
+    runs-on: ubuntu-latest
+    needs: [publish-pypi]
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload assets to GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG_NAME: ${{ github.event.release.tag_name }}
+        run: gh release upload "$TAG_NAME" dist/* --repo "$GH_REPO"

conda_workspaces-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,70 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/tests.yml"
+      - "conda_workspaces/**"
+      - "pixi.lock"
+      - "pyproject.toml"
+      - "tests/**"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/tests.yml"
+      - "conda_workspaces/**"
+      - "pixi.lock"
+      - "pyproject.toml"
+      - "tests/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: prefix-dev/setup-pixi@82d477f15f3a381dbcc8adc1206ce643fe110fb7 # v0.9.3
+        with:
+          environments: dev
+      - name: Lint
+        run: pixi run -e dev lint
+      - name: Format check
+        run: pixi run -e dev format-check
+
+  tests:
+    name: ${{ matrix.os }}, Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.13"]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: ubuntu-latest
+            python-version: "3.14"
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@82d477f15f3a381dbcc8adc1206ce643fe110fb7 # v0.9.3
+        with:
+          environments: test
+      - name: Run tests
+        run: pixi run -e test test-cov
+      - name: Upload coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: coverage-report
+          path: htmlcov/

conda_workspaces-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# pixi
+.pixi/
+
+# conda project-local envs
+.conda/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Docs
+docs/_build/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Type checking
+.ty/
+.mypy_cache/
+
+# Version file (auto-generated)
+conda_workspaces/_version.py

conda_workspaces-0.1.0/AGENTS.md

@@ -0,0 +1,148 @@
+# AGENTS.md — conda-workspaces coding guidelines
+
+## Project structure
+
+- CLI modules are separated by subcommand, mirroring conda's own CLI
+  layout. Each subcommand lives in its own module under
+  `conda_workspaces/cli/` (e.g., `init.py`, `install.py`, `list.py`,
+  `info.py`, `add.py`, `remove.py`, `clean.py`, `run.py`, `activate.py`).
+  `cli/main.py` contains parser configuration and dispatch;
+  `cli/__init__.py` is a thin re-export shim (`configure_parser`,
+  `execute`, `generate_parser`).
+
+- Parser implementations use submodules, not subpackages. The canonical
+  format parsers live at `conda_workspaces/parsers/toml.py`,
+  `conda_workspaces/parsers/pixi_toml.py`, and
+  `conda_workspaces/parsers/pyproject_toml.py` — plain modules, not
+  directories with `__init__.py`. Only create a subpackage when there
+  are multiple files to group.
+
+- Tests mirror the source structure. Tests for
+  `conda_workspaces/cli/install.py` live in `tests/cli/test_install.py`,
+  tests for `conda_workspaces/parsers/toml.py` live in
+  `tests/parsers/test_toml.py`, etc. Test module names match their
+  corresponding source module names.
+
+## Imports
+
+- Use relative imports for all intra-package references
+  (`from .models import WorkspaceConfig`,
+  `from ..exceptions import CondaWorkspacesError`).
+  Absolute `conda_workspaces.*` imports should only appear in tests
+  and entry points.
+
+- Inline (lazy) imports are reserved for performance-critical paths.
+  Acceptable cases: `plugin.py` hooks (loaded on every `conda`
+  invocation), `cli/main.py` subcommand dispatch (only the chosen
+  handler is loaded), `context.py` property methods (lazy by design),
+  and `parsers/toml.py` where `CondaTomlParser.parse()` delegates to
+  `PixiTomlParser` (breaks a real circular dependency since
+  `pixi_toml` imports helpers from `toml`). Everywhere else, imports
+  belong at the top of the module.
+
+## Dependencies
+
+- Minimize the dependency graph. Prefer stdlib or already-required
+  packages over adding new ones. When a single library covers multiple
+  use cases (e.g., `tomlkit` for both reading and writing TOML), use
+  it instead of carrying separate read-only and read-write libraries.
+
+- Pin minimum versions in `pyproject.toml` dependencies (e.g.,
+  `"tomlkit >=0.13"`), not exact versions.
+
+## Typing and linting
+
+- All code must be typed using modern annotations (`str | None` not
+  `Optional[str]`, `list[str]` not `List[str]`). `ClassVar` from
+  `typing` is the correct annotation for class-level attributes — it
+  is not deprecated.
+
+- Use `ty` for type checking and `ruff` for linting and formatting.
+  Both are configured in `pyproject.toml`.
+
+- Use `from __future__ import annotations` in all modules.
+
+## Testing
+
+- Tests are plain `pytest` functions — no `unittest.TestCase` or other class-based test grouping.
+  Do not group tests in classes; use module-level functions with descriptive names.
+
+- Do not use section comments (e.g., `# --- Section ---`) to group tests.
+  Relay on function naming and module structure for organization.
+
+- Use `pytest` native fixtures (`tmp_path`, `monkeypatch`, `capsys`)
+  instead of `unittest.mock`. Prefer `monkeypatch.setattr` with simple
+  fakes or recording closures over `MagicMock` / `patch`.
+
+- Use `pytest.mark.parametrize` extensively. When multiple test cases
+  exercise the same logic with different inputs, consolidate them into
+  a single parameterized test.
+
+- Shared fixtures belong in `conftest.py` at the appropriate level
+  (root `tests/conftest.py` for cross-cutting fixtures, subdirectory
+  `conftest.py` for module-specific ones).
+
+- Coverage is measured with `pytest-cov`. Thresholds and exclusions are
+  configured in `pyproject.toml` under `[tool.coverage.*]`. Run
+  `pixi run -e <test-env> test-cov` to generate a coverage report.
+
+## Conda integration
+
+- Follow standard conda CLI patterns: use `-n`/`--name` and
+  `-p`/`--prefix` for environment targeting, not custom flags like
+  `--environment`.
+
+- Use conda's own APIs where available (e.g., `conda.base.constants`,
+  `conda.base.context.context`, `context.plugins.raw_data` for
+  `.condarc` settings) rather than reimplementing platform detection or
+  config parsing.
+
+- The `add_output_and_prompt_options` helper from conda already
+  provides `--json`, `--dry-run`, `--yes`, `-v`, `-q`, `--debug`,
+  `--trace`, and `--console`. Do not add custom arguments that
+  duplicate these — it causes `ArgumentError: conflicting option
+  string` at runtime.
+
+- The plugin registers via `pluggy` hooks (`conda_subcommands`) and
+  the `[project.entry-points.conda]` entry point.
+
+## Parser search order
+
+- The parser registry searches for workspace manifests in this order:
+  1. `conda.toml` — conda-native workspace manifest
+  2. `pixi.toml` — pixi-native format (compatibility)
+  3. `pyproject.toml` — embedded under `[tool.conda.*]`,
+     `[tool.conda-workspaces.*]` (legacy), or `[tool.pixi.*]`
+
+- All parsers produce a `WorkspaceConfig` model, regardless of source
+  format. Parser-specific logic stays in the parser; downstream code
+  only depends on the model.
+
+## Documentation
+
+- Docs use Sphinx with `conda-sphinx-theme`, `myst-parser`, and
+  `sphinx-design`.
+
+- Follow the Diataxis framework: tutorials, how-to guides, reference,
+  and explanation sections.
+
+- Key relationship with pixi must be documented prominently:
+  `conda-workspaces` reads pixi-compatible manifests but delegates
+  solving and environment management to conda's own infrastructure.
+  It does not replace pixi — it brings workspace management into the
+  conda CLI.
+
+- Avoid excessive bold and italic in prose, list items, and headings.
+  Don't bold every list item or key term — let the text speak for
+  itself. In docstrings, use `*param*` for parameter names (standard
+  Sphinx convention) but avoid bold elsewhere.
+
+- Keep `sphinx-design` tab labels short. Use "pixi.toml" / "TOML" /
+  "pyproject.toml" instead of verbose labels when the tab content
+  already identifies the format. This prevents tab overflow on narrow
+  viewports.
+
+- The API reference is split into focused sub-pages by concern (models,
+  parsers, resolver, context, environments) rather than a single
+  monolithic page. The index uses `sphinx-design` grid cards for
+  navigation.

conda_workspaces-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to conda-workspaces will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## Unreleased
+
+## 0.1.0 — 2026-03-05
+
+### Added
+
+- Initial implementation of conda-workspaces plugin
+- `conda workspace` subcommand with `init`, `install`, `list`, `info`,
+  `add`, `remove`, `clean`, `run`, and `activate` subcommands
+- `cw` standalone CLI shortcut
+- Parser support for `pixi.toml`, `conda.toml`, and `pyproject.toml`
+  manifests
+- Multi-environment workspace model with composable features
+- Solve-group support for version coordination across environments
+- Per-platform dependency overrides via `[target.<platform>]`
+- PyPI dependency parsing (requires conda-pypi for installation)
+- Project-local environments under `.conda/envs/`
+- Sphinx documentation with conda-sphinx-theme
+- PyPI release workflow with trusted publishing

conda_workspaces-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,126 @@
+# Conda Organization Code of Conduct
+
+# The Short Version
+
+Be kind to others. Do not insult or put down others. Behave professionally. Remember that harassment and sexist, racist, or exclusionary jokes are not appropriate for the conda Organization.
+
+All communication should be appropriate for a professional audience including people of many different backgrounds. Sexual language and imagery is not appropriate.
+
+The conda Organization is dedicated to providing a harassment-free community for everyone, regardless of gender, sexual orientation, gender identity and expression, disability, physical appearance, body size, race, or religion. We do not tolerate harassment of community members in any form.
+
+Thank you for helping make this a welcoming, friendly community for all.
+
+## Report an Incident
+
+* Report a code of conduct incident [using a form](https://form.jotform.com/221527028480048).
+* Report a code of conduct incident via email: [conduct@conda.org](mailto:conduct@conda.org).
+* Contact [an individual committee member](#committee-membership) or [CoC event representative](#coc-representatives) to report an incident in confidence.
+
+ 
+
+And now the longer version...
+
+# Conda Organization Diversity Statement
+
+The conda Organization welcomes and encourages participation in our community by people of all backgrounds and identities. We are committed to promoting and sustaining a culture that values mutual respect, tolerance, and learning, and we work together as a community to help each other live out these values.
+
+We have created this diversity statement because we believe that a diverse community is stronger, more vibrant, and produces better software and better science. A diverse community where people treat each other with respect has more potential contributors, more sources for ideas, and fewer shared assumptions that might hinder development or research.
+
+Although we have phrased the formal diversity statement generically to make it all-inclusive, we recognize that there are specific identities that are impacted by systemic discrimination and marginalization. We welcome all people to participate in the conda Organization community regardless of their identity or background.
+
+# Conda Organization Code of Conduct: Introduction & Scope
+
+This code of conduct should be honored by everyone who participates in the conda Organization community. It should be honored in any conda Organization-related activities, by anyone claiming affiliation with the conda Organization, and especially when someone is representing the conda Organization in any role (including as an event volunteer or speaker).
+
+This code of conduct applies to all spaces managed by the conda Organization, including all public and private mailing lists, issue trackers, wikis, forums, and any other communication channel used by our community. The code of conduct equally applies at conda Organization events and governs standards of behavior for attendees, speakers, volunteers, booth staff, and event sponsors.
+
+This code is not exhaustive or complete. It serves to distill our understanding of a collaborative, inclusive community culture. Please try to follow this code in spirit as much as in letter, to create a friendly and productive environment that enriches the conda Organization community.
+
+The conda Organization Code of Conduct follows below.
+
+# Standards for Behavior
+
+The conda Organization is a worldwide community. All communication should be appropriate for a professional audience including people of many different backgrounds.
+
+**Please always be kind and courteous. There's never a need to be mean or rude or disrespectful.** Thank you for helping make this a welcoming, friendly community for all.
+
+We strive to:
+
+**Be empathetic, welcoming, friendly, and patient.** We remember that the conda Organization is crafted by human beings who deserve to be treated with kindness and empathy. We work together to resolve conflict and assume good intentions. We may all experience some frustration from time to time, but we do not allow frustration to turn into a personal attack. A community where people feel uncomfortable or threatened is not a productive one.
+
+**Be collaborative.** Our work depends on the participation of many people, and in turn others depend on our work. Open source communities depend on effective and friendly collaboration to achieve their goals.
+
+**Be inquisitive.** Nobody knows everything! Asking questions early avoids many problems later, so we encourage questions, although we may direct them to the appropriate forum. We will try hard to be responsive and helpful.
+
+**Be careful in the words that we choose.** We are careful and respectful in our communication and we take responsibility for our own speech. Be kind to others. Do not insult or put down other members of the community.
+
+## Unacceptable Behavior
+
+We are committed to making participation in this community a harassment-free experience.
+
+We will not accept harassment or other exclusionary behaviors, such as:
+
+- The use of sexualized language or imagery
+- Excessive profanity (please avoid curse words; people differ greatly in their sensitivity to swearing)
+- Posting sexually explicit or violent material
+- Violent or intimidating threats or language directed against another person
+- Inappropriate physical contact and/or unwelcome sexual attention or sexual comments
+- Sexist, racist, or otherwise discriminatory jokes and language
+- Trolling or insulting and derogatory comments
+- Written or verbal comments which have the effect of excluding people on the basis of membership in a specific group, including level of experience, gender, gender identity and expression, sexual orientation, disability, neurotype, personal appearance, body size, race, ethnicity, age, religion, or nationality
+- Public or private harassment
+- Sharing private content, such as emails sent privately or non-publicly, or direct message history, without the sender's consent
+- Continuing to initiate interaction (such as photography, recording, messaging, or conversation) with someone after being asked to stop
+- Sustained disruption of talks, events, or communications, such as heckling of a speaker
+- Publishing (or threatening to post) other people's personally identifying information ("doxing"), such as physical or electronic addresses, without explicit permission
+- Other unethical or unprofessional conduct
+- Advocating for, or encouraging, any of the above behaviors
+
+The conda Organization prioritizes marginalized people's safety over privileged people's comfort. The conda CoC Committee reserves the right not to act on complaints including, but not limited to:
+
+* 'Reverse' -isms, including 'reverse racism,' 'reverse sexism,' and 'cisphobia'.
+* Reasonable communication of boundaries, such as "leave me alone," "go away," or "I'm not discussing this with you."
+* Communicating in a 'tone' you don't find congenial.
+* Criticizing racist, sexist, cissexist, or otherwise oppressive behavior or assumptions.
+
+## Behavior Outside of conda Organization Spaces
+
+The CoC Committee does not influence behavior and membership in spaces outside the conda Organization. However, if you are being harassed by a member of the conda community outside our spaces, you may still report it to the CoC Committee. We will take all good-faith reports of harassment by conda community members seriously. This includes harassment outside our spaces and harassment that took place at any point in time.
+
+The CoC Committee reserves the right to exclude people from conda Organization spaces based on their past behavior, including behavior outside conda Organization spaces and behavior towards people who are not in the conda community.
+
+# Confidentiality and Public Statements to the Community
+
+The CoC Committee will keep the identity of the reporter confidential.
+
+Whenever possible, CoC cases will be reported to the community. The level of detail in reports will vary from case to case. Reports will describe at least the type of infraction that was reported, and the Committee's decision and any action taken.  In most cases, the report will not include personally identifiable information.
+
+# Reporting Guidelines
+
+If you believe someone is violating the code of conduct, please report this in a timely manner. Code of conduct violations reduce the value of the community for everyone. The conda Code of Conduct (CoC) Committee and the conda Organization take reports of misconduct very seriously and are committed to preserving and maintaining the welcoming nature of our community.
+
+All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The conda CoC Committee commits to maintaining confidentiality with regard to the reporter of an incident.
+
+## How to Submit a Report
+
+You can report an incident:
+
+* via the [Incident Reporting Form](https://form.jotform.com/221527028480048)
+* via email: [conduct@conda.org](mailto:conduct@conda.org)
+* contact [an individual committee member](#committee-membership) to report an incident in confidence.
+
+## Enforcement
+
+The CoC Committee will review all reports and determine appropriate action. Potential consequences include:
+
+- Nothing (if no violation occurred)
+- Private feedback or reprimand
+- Warning to cease the behavior
+- Temporary or permanent ban from conda Organization spaces
+- Other responses deemed necessary and appropriate
+
+For the full details on enforcement, reporting, and committee membership, see the [conda Organization Code of Conduct](https://github.com/conda/conda/blob/main/CODE_OF_CONDUCT.md).
+
+# License
+
+This code of conduct is based on the [conda Organization Code of Conduct](https://github.com/conda/conda/blob/main/CODE_OF_CONDUCT.md), which is licensed under the [Creative Commons Attribution 3.0 Unported License](https://creativecommons.org/licenses/by/3.0/).

conda_workspaces-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing to conda-workspaces
+
+Thank you for your interest in improving conda-workspaces! This document
+describes how to contribute to the project.
+
+## Code of Conduct
+
+This project follows the [conda Organization Code of Conduct](CODE_OF_CONDUCT.md).
+Please read it before participating.
+
+## Getting started
+
+1. Fork the repository on [GitHub](https://github.com/conda-incubator/conda-workspaces).
+2. Clone your fork locally.
+3. Install [pixi](https://pixi.sh) (used for development environments).
+4. Run the tests to make sure everything works:
+
+   ```bash
+   pixi run test
+   ```
+
+## Development setup
+
+conda-workspaces uses pixi for development environment management. The
+available tasks are defined in `pixi.toml`:
+
+```bash
+pixi run test          # run tests
+pixi run test-cov      # run tests with coverage
+pixi run lint          # run ruff linter
+pixi run format        # run ruff formatter
+pixi run typecheck     # run ty type checker
+pixi run docs          # build documentation
+```
+
+## Making changes
+
+### Branch workflow
+
+1. Create a new branch from `main` for your changes.
+2. Keep changes focused on a single issue or feature.
+3. Write tests for new functionality.
+4. Make sure all tests pass before submitting.
+
+### Code style
+
+- All code must be typed using modern annotations (`str | None`, `list[str]`).
+- Use `from __future__ import annotations` in all modules.
+- Use relative imports for intra-package references.
+- Run `pixi run lint` and `pixi run format` before committing.
+- Run `pixi run typecheck` to verify type annotations.
+
+### Testing
+
+- Tests are plain `pytest` functions — no `unittest.TestCase` classes.
+- Use `pytest.mark.parametrize` for multiple test cases with the same logic.
+- Use `monkeypatch` and native pytest fixtures instead of `unittest.mock`.
+- Tests mirror the source structure (e.g., tests for
+  `conda_workspaces/cli/install.py` live in `tests/cli/test_install.py`).
+
+### Documentation
+
+- Docs use Sphinx with MyST Markdown.
+- Build locally with `pixi run docs`.
+- Follow the [Diataxis framework](https://diataxis.fr/) for new content.
+
+## Submitting a pull request
+
+1. Push your branch to your fork.
+2. Open a pull request against `main`.
+3. Describe what your change does and why.
+4. Link any related issues.
+5. Make sure CI passes.
+
+## Conda Contributor License Agreement
+
+To contribute to conda ecosystem projects, you need to sign the
+[Conda Contributor License Agreement (CLA)](https://conda.io/en/latest/contributing.html#conda-contributor-license-agreement).
+
+## Generative AI
+
+You're welcome to use generative AI tools when contributing. However:
+
+- You are responsible for all of your contributions. Review and understand any
+  AI-generated content before including it in a pull request.
+- Be prepared to discuss changes during review — do not paste AI responses
+  verbatim.
+- Make minimal, focused changes that match the existing style and patterns.
+- Ensure AI-assisted changes actually fix the underlying problem rather than
+  altering tests to make them pass.
+
+Pull requests consisting of unchecked AI-generated content may be closed.
+
+## Getting help
+
+- Open an [issue](https://github.com/conda-incubator/conda-workspaces/issues) for
+  bug reports or feature requests.
+- Join the [conda community chat](https://conda.zulipchat.com) for questions.