docs: align README, Fern docs, and skills for agent/python/rest workflows

.gitignore

@@ -17,9 +17,7 @@ htmlcov/
 **/*~
 **/#*#
 
-**/*.json
+/*.json
 !example.json
-!tests/fixtures/**/*.json
-!fern/fern.config.json
 
 **/.DS_Store

AGENT.md

@@ -1,6 +1,7 @@
 # Agent guide — Course Constraint Scheduler
 
 This file orients coding agents to the repository: how to build, test, and change the right places without guesswork.
+If you are a human contributor, start with [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md) for user-facing and process details.
 
 ## What this project is
 
@@ -44,7 +45,7 @@ skills/            # task playbooks (SKILL.md per subfolder) for assistants and
 ## Conventions that trip people up
 
 1. **`Course` naming**: `scheduler.config` uses `Course` as a **course-id string** type in JSON config. `scheduler.models` defines a **`Course` class** (credits, meetings, etc.). `CourseInstance.course` is the model; use **`.course.course_id`** for the config-style id. (See README “Note on naming”.)
-2. **Generated artifacts**: After changing **`server.py`** or API-facing models, refresh **`fern/openapi.json`**. After **`CombinedConfig`** / config models change, refresh **`fern/docs/assets/combined-config.schema.json`**. After public **docstrings** change, refresh **`fern/docs/pages/python/reference.mdx`** — see CONTRIBUTING.
+2. **Generated artifacts**: After changing **`src/scheduler/server.py`** or API-facing models, refresh **`fern/openapi.json`**. After **`CombinedConfig`** / config models change, refresh **`fern/docs/assets/combined-config.schema.json`**. After public **docstrings** change, refresh **`fern/docs/pages/python/reference.mdx`** — see CONTRIBUTING.
 3. **Style**: **Ruff** is authoritative (`pyproject.toml`: line length **120**, `py312`). CONTRIBUTING matches this; when in doubt follow **`pyproject.toml`**.
 
 ## Skills

CONTRIBUTING.md

@@ -107,10 +107,10 @@ Configuration lives in `.pre-commit-config.yaml` (prek is compatible with this f
 
 ```bash
 # Test the scheduler
-python -m scheduler.main --help
+uv run python -m scheduler.main --help
 
 # Test the server
-python -m scheduler.server --help
+uv run python -m scheduler.server --help
 
 # Run tests
 uv run pytest
@@ -266,7 +266,8 @@ def generate_schedule(config: SchedulerConfig) -> List[CourseInstance]:
     - RuntimeError: If no valid schedule can be generated.
 
     **Example:**
-        >>> config = load_config_from_file("config.json")
+        >>> from scheduler.config import CombinedConfig
+        >>> config = load_config_from_file(CombinedConfig, "config.json")
         >>> schedule = generate_schedule(config, limit=5)
         >>> print(f"Generated {len(schedule)} courses")
     """
@@ -322,6 +323,7 @@ if not faculty_available:
 - Update **Fern** pages under **`fern/docs/pages/`** (configuration, welcome, development)
 - Update README.md for new features
 - Regenerate **`fern/docs/assets/combined-config.schema.json`** with `uv run python scripts/export_config_schema.py` when `CombinedConfig` changes
+- Keep generated Fern artifacts committed when they are used by docs publishing (`fern/openapi.json`, `fern/docs/assets/combined-config.schema.json`, `fern/docs/pages/python/reference.mdx`)
 - Preview locally: `npm install -g fern-api` then `fern docs dev` (after the generate scripts above)
 
 ## Submitting Changes
@@ -389,7 +391,7 @@ We use [Semantic Versioning](https://semver.org/):
 ### Release Steps
 
 1. **Update Version**: Update version in `pyproject.toml`
-2. **Changelog**: Update `CHANGELOG.md` with new changes
+2. **Release Notes**: Prepare release notes in the GitHub release description (or update `CHANGELOG.md` if your release includes one)
 3. **Tag Release**: Create git tag for the version
 4. **Build Package**: Build and test the package
 5. **Publish**: Publish to PyPI

README.md

@@ -2,6 +2,18 @@
 
 A powerful constraint satisfaction solver for generating academic course schedules using the Z3 theorem prover.
 
+## Start Here by Audience
+
+- **Coding agents and contributors**: read [AGENT.md](AGENT.md), [CONTRIBUTING.md](CONTRIBUTING.md), and [skills/README.md](skills/README.md).
+- **Python API users**: jump to [Python API](#python-api).
+- **REST API users**: jump to [REST API](#rest-api).
+
+### Naming Cheat Sheet
+
+- **Repository**: `mucsci/scheduler`
+- **Package on PyPI**: `course-constraint-scheduler`
+- **Python import**: `scheduler`
+
 ## Overview
 
 The Course Constraint Scheduler is designed to solve complex academic scheduling problems by modeling them as constraint satisfaction problems. It can handle:
@@ -77,16 +89,22 @@ for schedule in scheduler.get_models():
 # Start the server with custom options
 scheduler-server --port 8000 --host 0.0.0.0 --log-level info --workers 16
 
-# Submit a schedule request
+# 1) Submit a schedule request
 curl -X POST "http://localhost:8000/submit" \
   -H "Content-Type: application/json" \
   -d @example.json
 
-# Get the next schedule
-curl -X POST "http://localhost:8000/schedules/{schedule_id}/next"
+# 2) The submit response includes the schedule_id you need
+# {"schedule_id":"f9f2...","endpoint":"/schedules/f9f2..."}
+
+# 3) Use that schedule_id for schedule generation and progress
+curl -X POST "http://localhost:8000/schedules/f9f2.../next"
+curl -X GET "http://localhost:8000/schedules/f9f2.../count"
 
-# Check generation progress
-curl -X GET "http://localhost:8000/schedules/{schedule_id}/count"
+# Optional endpoints
+curl -X GET "http://localhost:8000/schedules/f9f2.../details"
+curl -X GET "http://localhost:8000/schedules/f9f2.../index/0"
+curl -X DELETE "http://localhost:8000/schedules/f9f2.../delete"
 ```
 
 ### Server deployment and security
@@ -104,6 +122,12 @@ See [SECURITY.md](SECURITY.md) for how to report vulnerabilities.
 **Published docs (configuration, Python API, REST API, development):**
 [https://mucsci-scheduler.docs.buildwithfern.com](https://mucsci-scheduler.docs.buildwithfern.com)
 
+If you are changing code or docs in this repo:
+
+- Contributor workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Agent workflow: [AGENT.md](AGENT.md)
+- Skill playbooks: [skills/README.md](skills/README.md)
+
 CI publishes this site on pushes to `main` that touch `fern/`, `scripts/`, or `src/scheduler/` (see `.github/workflows/docs.yml`). The repository needs a **`FERN_TOKEN`** Actions secret from the Fern CLI (`fern token`) or dashboard.
 
 ### Local REST API (OpenAPI UI)
@@ -127,10 +151,20 @@ uv run python scripts/gen_python_api_mdx.py
 fern docs dev
 ```
 
+Generated artifacts used by Fern:
+
+- `fern/openapi.json` (from FastAPI routes/models)
+- `fern/docs/assets/combined-config.schema.json` (from `CombinedConfig`)
+- `fern/docs/pages/python/reference.mdx` (from public docstrings)
+
+Regenerate these with the scripts above after API/config/docstring changes.
+
 ### Configuration quick link
 
 A short pointer to the new docs location: [docs/configuration.md](./docs/configuration.md).
 
+`example.json` is included in this repository for local cloning workflows. If you need a minimal sample, use `tests/fixtures/minimal_config.json`.
+
 ## Configuration
 
 The scheduler uses a JSON configuration file that defines:
@@ -227,8 +261,8 @@ The scheduler is built with a modular architecture:
 
 ```bash
 # Clone the repository
-git clone <repository-url>
-cd course-constraint-scheduler
+git clone https://github.com/mucsci/scheduler.git
+cd scheduler
 
 # Install dependencies (includes dev tools via uv default-groups; see pyproject.toml)
 uv sync

docs/configuration.md

@@ -7,3 +7,9 @@ The configuration documentation now lives on the **Fern** docs site:
 Source for those pages is in the repository under [`fern/docs/pages/configuration/`](../fern/docs/pages/configuration/).
 
 A machine-readable JSON Schema for the full config is at [`fern/docs/assets/combined-config.schema.json`](../fern/docs/assets/combined-config.schema.json).
+
+If you are working from a fresh checkout and the schema file is missing, regenerate it with:
+
+```bash
+uv run python scripts/export_config_schema.py
+```

fern/docs.yml

@@ -62,6 +62,10 @@ navigation:
         path: docs/pages/python/overview.mdx
       - page: Reference
         path: docs/pages/python/reference.mdx
+  - section: REST API
+    contents:
+      - page: Integration quickstart
+        path: docs/pages/rest/quickstart.mdx
   - api: REST API
   - section: Development
     contents: