From 61fe89f2671c85816b012491a3c89f5421f16d23 Mon Sep 17 00:00:00 2001
From: BadoniShreyansh <badonishreyansh@gmail.com>
Date: Thu, 30 Apr 2026 11:37:19 +0530
Subject: [PATCH 1/2] examples/: add a README explaining what's there

---
 examples/README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 examples/README.md

diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..e57f82a
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,51 @@
+# Examples
+
+Runnable scripts that show one feature each. They import townsquare modules directly — no HTTP calls, no Docker exec. Think of them as reference implementations for specific workflows.
+
+## Available scripts
+
+| Script                                  | What it does |
+| --------------------------------------- | ------------ |
+| _(empty — first contributor adds here)_ |              |
+
+<!-- When adding: script name, one-line description. Update this table. -->
+
+## How to run
+
+First: get townsquare running. The full setup is in [docs/SELF_HOSTING.md](../docs/SELF_HOSTING.md). Quick version:
+
+```bash
+git clone https://github.com/townsquare-os/townsquare
+cd townsquare
+cp example.env .env
+make gen-secrets         # paste into .env
+# fill GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, WORKSPACE_DOMAIN, ANTHROPIC_API_KEY
+make up
+```
+
+Install Python dependencies locally (examples need them):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[google,all]"
+```
+
+Run any example:
+
+```bash
+source .venv/bin/activate
+python examples/<script>.py
+```
+
+Each script reads `.env` from the repo root. Some need extra connectors (`SLACK_CLIENT_ID`, GitHub PAT) — check the script's header comment for specifics.
+
+## What makes a good example
+
+- Demonstrates **one** workflow (federated query, connector usage, agent invocation, wiki/CRM operations, user management).
+- Imports from `townsquare.*` — shows how to use the library programmatically.
+- Inline comments explaining key decisions and API patterns.
+- Graceful error handling with helpful messages.
+- Header comment listing required `.env` variables beyond the defaults.
+
+When you add a script, update the table above.

From 3a16a1e6070f18fc382d22c1c7bcc478ae9f1e8c Mon Sep 17 00:00:00 2001
From: BadoniShreyansh <badonishreyansh@gmail.com>
Date: Sat, 2 May 2026 00:50:51 +0530
Subject: [PATCH 2/2] Updated examples/README according to comments

---
 examples/README.md | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/examples/README.md b/examples/README.md
index e57f82a..8402c34 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,14 +1,12 @@
 # Examples
 
-Runnable scripts that show one feature each. They import townsquare modules directly — no HTTP calls, no Docker exec. Think of them as reference implementations for specific workflows.
+Runnable scripts that show one feature each. Some import `townsquare.*` directly (library usage); others call a running server’s HTTP endpoints (integration patterns). Think of them as reference implementations for specific workflows.
 
 ## Available scripts
 
-| Script                                  | What it does |
-| --------------------------------------- | ------------ |
-| _(empty — first contributor adds here)_ |              |
-
-<!-- When adding: script name, one-line description. Update this table. -->
+| Script                                   | What it does |
+| ---------------------------------------- | ------------ |
+| _(none yet — be the first contributor!)_ |              |
 
 ## How to run
 
@@ -28,7 +26,15 @@ Install Python dependencies locally (examples need them):
 ```bash
 python -m venv .venv
 source .venv/bin/activate
-pip install -e ".[google,all]"
+
+# Minimal (works for most examples)
+pip install -e ".[dev]"
+
+# If the example uses external connectors (Slack, Notion, GitHub, etc.)
+pip install -e ".[all,dev]"
+
+# Or, for very simple examples with no extras
+pip install -e .
 ```
 
 Run any example:
@@ -43,7 +49,8 @@ Each script reads `.env` from the repo root. Some need extra connectors (`SLACK_
 ## What makes a good example
 
 - Demonstrates **one** workflow (federated query, connector usage, agent invocation, wiki/CRM operations, user management).
-- Imports from `townsquare.*` — shows how to use the library programmatically.
+- Uses either `townsquare.*` imports (library usage) or HTTP calls to a running server (integration patterns).
+- Loads `.env` from the repo root (e.g., via `python-dotenv` or `townsquare.settings.get_settings()`).
 - Inline comments explaining key decisions and API patterns.
 - Graceful error handling with helpful messages.
 - Header comment listing required `.env` variables beyond the defaults.