> ## Documentation Index
> Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Setup

<div className="not-prose my-4 rounded-md border border-gray-200 bg-gray-50 p-2 text-sm dark:border-gray-800 dark:bg-gray-900/40">
  <div className="mb-2 px-1 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">Need help?</div>

  <div className="flex flex-wrap gap-2">
    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://discord.gg/sDE2HhGTg4" target="_blank" rel="noreferrer">
      <Icon icon="discord" iconType="brands" size={14} />

      <span>Ask in Discord</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/issues/new/choose" target="_blank" rel="noreferrer">
      <Icon icon="github" iconType="brands" size={14} />

      <span>Open a GitHub issue</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/SUPPORT.md" target="_blank" rel="noreferrer">
      <Icon icon="life-ring" size={14} />

      <span>Support guide</span>
    </a>
  </div>
</div>

This shared setup guide is for the public starter projects referenced by the
Practitioner, Builder, and Contributor paths.

## What this setup is for

* reading the Agent Systems Handbook locally
* running the current repo-owned starter code
* verifying example projects before or after contribution work

The current sample projects are intentionally lightweight Python starters. They
are small enough to inspect quickly and validate without a framework-specific
toolchain.

## Prerequisites

* Git
* Python 3.9 or newer
* a terminal on macOS, Linux, or WSL

## Clone the repository

```bash theme={null}
git clone https://github.com/Prompthon-IO/agent-systems-handbook.git
cd agent-systems-handbook
```

## Optional virtual environment

The current starter checks use only the Python standard library, but an
isolated environment is still a good default:

```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
python3 --version
```

## Verify the current starter code

Run the repo-level smoke check:

```bash theme={null}
python3 scripts/verify_example_projects.py
```

This verifies the current starter code under:

* `patterns/examples/`
* `systems/examples/`
* `ecosystem/examples/`
* `case-studies/examples/`

## Optional Git hook for filename casing

If you contribute from Windows, macOS, or any case-insensitive filesystem,
install the shared Git hooks before pushing:

```bash theme={null}
git config core.hooksPath githooks
```

The current `pre-push` hook runs:

```bash theme={null}
python3 scripts/check_filename_casing.py
```

This catches case-only path conflicts and tracked-path casing drift before the
push reaches CI or a Linux-based review environment.

## What to expect

* The check validates the current code sketches and example flows.
* The current projects are still documented as `starter` examples, not full
  production applications.
* Some starters demonstrate state shape or control flow without shipping the
  surrounding transport, persistence, or framework runtime yet.

## If you are contributing

* Keep example projects in lane-local `examples/` folders.
* Declare project status as `starter`, `partial`, or `runnable`.
* If you change executable starter code, update
  `scripts/verify_example_projects.py` in the same change.