orchcore 0.1.0__tar.gz

orchcore-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# AI tool configurations
+.claude/
+.codex/
+AGENTS.md
+CLAUDE.md
+
+# Documentation (generated/managed separately)
+docs/
+
+# OS files
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Python
+src/orchcore/_version.py
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+.env
+.env.*
+!.env.example
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.settings/
+.classpath
+
+# Node (if applicable)
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Testing / Coverage
+.coverage
+.coverage.*
+htmlcov/
+.hypothesis/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Logs
+*.log
+logs/
+
+# Secrets / Credentials
+*.pem
+*.key
+credentials.json
+secrets.yaml
+secrets.yml

orchcore-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.8
+    hooks:
+      - id: ruff-check
+        args:
+          - --fix
+          - --exit-non-zero-on-fix
+      - id: ruff-format

orchcore-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+## [0.1.0](https://github.com/AbdelazizMoustafa10m/orchcore/compare/v0.0.1...v0.1.0) (2026-03-28)
+
+
+### Features
+
+* add phase 3 orchestration modules ([ad9cff0](https://github.com/AbdelazizMoustafa10m/orchcore/commit/ad9cff0f38e52dadf6eecc2cf5cea09a30dcbc39))
+* add phase 4 recovery and telemetry ([0a7e646](https://github.com/AbdelazizMoustafa10m/orchcore/commit/0a7e64618b4947591dab82fc24611a3bac8adf0a))
+* add stream processing pipeline with full test coverage (Phase 1) ([68ea98f](https://github.com/AbdelazizMoustafa10m/orchcore/commit/68ea98fb09e94b230647d34bfb0ec5546fc3f7e6))
+* add telemetry extra dependencies ([1472297](https://github.com/AbdelazizMoustafa10m/orchcore/commit/147229700c44df204e33bd44e950f028220f79be))
+* implement phase 2 orchestration modules ([656c26a](https://github.com/AbdelazizMoustafa10m/orchcore/commit/656c26ab22bccac0d1c3cadc587d29ab2d2086d0))
+* scaffold orchcore project structure (Phase 0) ([c15bc49](https://github.com/AbdelazizMoustafa10m/orchcore/commit/c15bc49e80e3ed1f034e5659964da37224965e04))
+
+
+### Bug Fixes
+
+* add explicit type annotations to reach 100% pyright verifytypes score ([8f8cead](https://github.com/AbdelazizMoustafa10m/orchcore/commit/8f8cead52d083fa9a7144e29d34ddaead3cfa44c))
+* add py.typed marker and use uv in Makefile ([ee6b0d0](https://github.com/AbdelazizMoustafa10m/orchcore/commit/ee6b0d0feed3123f873e5bc72c50453e33360f53))
+* **ci:** install dev extras in CI workflow ([4c95321](https://github.com/AbdelazizMoustafa10m/orchcore/commit/4c95321894068cee83bce9ce7e6a3b585666ef7a))
+* **ci:** update codeql-action to v3.35.1 in scorecards workflow ([38395fe](https://github.com/AbdelazizMoustafa10m/orchcore/commit/38395fef73fa2b57807d6edbc5982b35a8b583eb))
+* resolve 10 audit findings across stream, pipeline, workspace, and registry modules ([2f5789b](https://github.com/AbdelazizMoustafa10m/orchcore/commit/2f5789b827650e6e91fdaad5a4898ec1e4947978))
+* resolve 15 audit findings across pipeline, stream, runner, and config modules ([5ac8c08](https://github.com/AbdelazizMoustafa10m/orchcore/commit/5ac8c0807156c045c03eaf241d9018f10843019c))
+* resolve 21 audit findings across source and test modules ([2729424](https://github.com/AbdelazizMoustafa10m/orchcore/commit/272942401e5db72502150e472398439c5e6085b2))
+* resolve 50 audit findings across all orchcore modules ([aca114d](https://github.com/AbdelazizMoustafa10m/orchcore/commit/aca114dc8d3072f67ffeebf3a4996df4efc2aa78))
+* **tests:** make integration and template tests cross-platform ([5e83ae7](https://github.com/AbdelazizMoustafa10m/orchcore/commit/5e83ae72686c152d03c37497aa0c6d9e0c22c602))
+
+
+### Documentation
+
+* add CI, release, and PyPI badges to README ([0da542c](https://github.com/AbdelazizMoustafa10m/orchcore/commit/0da542cff0227d46d3f14f920b32687ce4567ac7))
+* add project documentation site and lean README ([09626eb](https://github.com/AbdelazizMoustafa10m/orchcore/commit/09626eb3c08c58d5d30a8e22697b17de7d1906e7))
+* fix 10 audit findings and add 5 missing module guides ([c09a74f](https://github.com/AbdelazizMoustafa10m/orchcore/commit/c09a74fbb4ac02e35c9dd06352734ee61a42aa80))
+* fix 16 remaining documentation inaccuracies across doc/ and docs/ ([147fa5a](https://github.com/AbdelazizMoustafa10m/orchcore/commit/147fa5a17c1444c3a4a7b659ed4afbcc3d3a8d99))
+* fix 5 remaining inaccuracies in guides ([af52fe9](https://github.com/AbdelazizMoustafa10m/orchcore/commit/af52fe95858d89bfe0d626d8830397fc2a681050))
+* fix SignalManager description to match implementation ([c536532](https://github.com/AbdelazizMoustafa10m/orchcore/commit/c536532ca3a9f1a7f8564af6a72039edfebfec74))
+* sync stream parser documentation ([e8991d1](https://github.com/AbdelazizMoustafa10m/orchcore/commit/e8991d131802d13d7e37848ec245408b93e33fee))
+* sync telemetry extra guidance ([0aa047e](https://github.com/AbdelazizMoustafa10m/orchcore/commit/0aa047e2a032d87ac8ec61ce4149030c4c85bdb3))
+
+
+### Build System
+
+* add pyright verifytypes for public API type completeness checks ([400f031](https://github.com/AbdelazizMoustafa10m/orchcore/commit/400f03198118fab7cbcc735d9e98188b01cd2fa3))
+* switch to git-tag-based versioning via hatch-vcs ([221bf9d](https://github.com/AbdelazizMoustafa10m/orchcore/commit/221bf9d91b1b0a5197d2ff45610597299ef13ce7))
+
+
+### CI/CD
+
+* add automated releases with release-please and commit linting ([8ebfb7d](https://github.com/AbdelazizMoustafa10m/orchcore/commit/8ebfb7dc1b1c1812e25735421382f715132e50b1))
+* add automatic GitHub Release creation on publish ([632d88d](https://github.com/AbdelazizMoustafa10m/orchcore/commit/632d88dc66fe11730a8578dc401c0655acfdbb25))
+* add GitHub Actions workflows for CI and PyPI publishing ([60648de](https://github.com/AbdelazizMoustafa10m/orchcore/commit/60648de1c648805acca08641c45c1eec0398ebdd))
+* remove unnecessary Test PyPI workflow ([df2894a](https://github.com/AbdelazizMoustafa10m/orchcore/commit/df2894a1b17f5e3b91210051ab804b32b3a690a9))
+
+
+### Tests
+
+* add Hypothesis coverage for stream parsers ([5809e97](https://github.com/AbdelazizMoustafa10m/orchcore/commit/5809e976342792242e6b3db60c14f9bce2fc8874))
+
+## Changelog
+
+All notable changes to this project will be documented in this file.
+
+This changelog is automatically generated by
+[release-please](https://github.com/googleapis/release-please) from
+[conventional commits](https://www.conventionalcommits.org/).

orchcore-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,108 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in the orchcore
+community a harassment-free experience for everyone, regardless of age, body size, visible or
+invisible disability, ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance, race, religion,
+or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive,
+and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for this community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Taking responsibility, apologizing to those affected by our mistakes, and learning from the
+  experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their
+  explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of acceptable
+behavior and will take appropriate and fair corrective action in response to any behavior that
+they deem inappropriate, threatening, offensive, or harmful.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits,
+code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct,
+and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is
+officially representing the community in public spaces. Examples of representing our community
+include using an official project email address, posting via an official social media account, or
+acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project
+maintainer using a private contact method listed on the repository owner profile. All complaints
+will be reviewed and investigated promptly and fairly.
+
+All maintainers are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for
+any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or
+unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the
+nature of the violation and an explanation of why the behavior was inappropriate. A public apology
+may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people
+involved, including unsolicited interaction with those enforcing the Code of Conduct, for a
+specified period of time. This includes avoiding interactions in community spaces as well as
+external channels like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate
+behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the
+community for a specified period of time. No public or private interaction with the people
+involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed
+during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including
+sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement
+of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1, available at
+[contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).

orchcore-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to orchcore
+
+Thank you for your interest in contributing to orchcore!
+
+For the full contributing guide covering development setup, commands, testing, code standards,
+and pull request expectations, see
+[doc/development/contributing.md](doc/development/contributing.md).
+
+## Quick Start
+
+```bash
+git clone https://github.com/AbdelazizMoustafa10m/orchcore.git
+cd orchcore
+uv pip install -e ".[dev]"
+make check  # lint + typecheck + test; must pass before submitting
+```
+
+## Commit Convention
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/). Pull request
+titles are validated automatically in CI.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+Please report security issues privately as described in [SECURITY.md](SECURITY.md).

orchcore-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Abdelaziz Abdelrasol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orchcore-0.1.0/Makefile

@@ -0,0 +1,30 @@
+.PHONY: install lint typecheck test check clean verifytypes
+
+install:
+	uv pip install -e ".[dev]"
+
+lint:
+	ruff check src/ tests/
+	ruff format --check src/ tests/
+
+format:
+	ruff format src/ tests/
+	ruff check --fix src/ tests/
+
+typecheck:
+	mypy src/orchcore/ --strict
+
+test:
+	pytest tests/ -v
+
+check: lint typecheck test
+	@echo "All checks passed."
+
+verifytypes:
+	uv run pyright --verifytypes orchcore --ignoreexternal
+
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type d -name .mypy_cache -exec rm -rf {} +
+	find . -type d -name .pytest_cache -exec rm -rf {} +
+	rm -rf dist/ build/ *.egg-info

orchcore-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: orchcore
+Version: 0.1.0
+Summary: Reusable orchestration core for AI coding agent CLI pipelines
+Project-URL: Homepage, https://github.com/AbdelazizMoustafa10m/orchcore
+Project-URL: Repository, https://github.com/AbdelazizMoustafa10m/orchcore
+Project-URL: Documentation, https://abdelazizmoustafa10m.github.io/orchcore
+Project-URL: Issues, https://github.com/AbdelazizMoustafa10m/orchcore/issues
+Project-URL: Changelog, https://github.com/AbdelazizMoustafa10m/orchcore/blob/main/CHANGELOG.md
+Author: Abdelaziz Abdelrasol
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic-settings>=2.7
+Requires-Dist: pydantic>=2.10
+Provides-Extra: dev
+Requires-Dist: commitizen>=3.29; extra == 'dev'
+Requires-Dist: coverage>=7.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == 'rich'
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api>=1.29; extra == 'telemetry'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.29; extra == 'telemetry'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.29; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk>=1.29; extra == 'telemetry'
+Provides-Extra: tui
+Requires-Dist: textual>=0.40; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# orchcore
+
+> Reusable orchestration core for AI coding agent CLI pipelines.
+
+[![CI](https://github.com/AbdelazizMoustafa10m/orchcore/actions/workflows/ci.yml/badge.svg)](https://github.com/AbdelazizMoustafa10m/orchcore/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/AbdelazizMoustafa10m/orchcore)](https://github.com/AbdelazizMoustafa10m/orchcore/releases)
+[![PyPI](https://img.shields.io/pypi/v/orchcore)](https://pypi.org/project/orchcore/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/AbdelazizMoustafa10m/orchcore/badge)](https://scorecard.dev/viewer/?uri=github.com/AbdelazizMoustafa10m/orchcore)
+[![mypy: strict](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy-lang.org/)
+[![Ruff](https://img.shields.io/badge/linter-ruff-orange.svg)](https://docs.astral.sh/ruff/)
+[![Coverage](https://codecov.io/gh/AbdelazizMoustafa10m/orchcore/graph/badge.svg)](https://codecov.io/gh/AbdelazizMoustafa10m/orchcore)
+
+## What is orchcore?
+
+orchcore is an async-first Python 3.12+ library that provides unified infrastructure for launching, monitoring, and managing multiple AI coding agent CLIs (Claude, Codex, Gemini, Copilot, OpenCode) as subprocesses through phase-based pipelines. It was extracted from four production orchestration systems — Planora, Articles, Finvault, and Raven — eliminating 60-70% of duplicated infrastructure so consuming projects only implement domain-specific logic.
+
+## Features
+
+- **Multi-agent subprocess orchestration** — async launch, stream capture, concurrency control
+- **Unified stream processing** — 4-stage pipeline normalizes 5 JSONL formats into a single `StreamEvent` model
+- **DAG-based phase pipelines** — sequential/parallel execution with dependency ordering and resume
+- **Rate-limit recovery** — automatic detection, timezone-aware reset parsing, exponential backoff
+- **Layered configuration** — TOML files, env vars, CLI overrides, named profiles
+- **Protocol-based UI** — `UICallback` decouples engine from display (Rich, Textual, headless)
+- **Registry-as-data** — new agent support via TOML config alone, zero code changes
+- **Graceful shutdown** — SIGINT/SIGTERM with subprocess cleanup and state preservation
+
+## Installation
+
+```bash
+uv pip install orchcore
+```
+
+From source:
+
+```bash
+git clone https://github.com/AbdelazizMoustafa10m/orchcore.git
+cd orchcore
+uv pip install -e ".[dev]"
+```
+
+**Requirements:** Python 3.12+
+
+## Quick Start
+
+### 1. Define Agents
+
+```toml
+# agents.toml
+[agents.claude]
+binary = "claude"
+model = "claude-sonnet-4-20250514"
+subcommand = "-p"
+stream_format = "claude"
+
+[agents.claude.flags]
+plan = ["--think", "--verbose"]
+
+[agents.claude.output_extraction]
+strategy = "jq_filter"
+jq_expression = ".content[0].text"
+```
+
+### 2. Run a Pipeline
+
+```python
+import asyncio
+from pathlib import Path
+from orchcore.pipeline import PipelineRunner, PhaseRunner, Phase
+from orchcore.registry import AgentRegistry, AgentMode, ToolSet
+from orchcore.runner import AgentRunner
+from orchcore.ui import NullCallback
+
+async def main() -> None:
+    registry = AgentRegistry()
+    registry.load_from_toml(Path("agents.toml"))
+
+    phase = Phase(
+        name="planning",
+        agents=["claude"],
+        tools=ToolSet(internal=["Read", "Glob", "Grep"], permission="read-only"),
+    )
+
+    runner = AgentRunner()
+    phase_runner = PhaseRunner(runner, registry, max_concurrency=4)
+    pipeline = PipelineRunner(phase_runner)
+
+    result = await pipeline.run_pipeline(
+        phases=[phase],
+        prompts={"planning": "Analyze the codebase and create a plan."},
+        ui_callback=NullCallback(),
+        mode=AgentMode.PLAN,
+    )
+    print(f"Success: {result.success} | Cost: ${result.total_cost_usd}")
+
+asyncio.run(main())
+```
+
+## Modules
+
+| Module | Purpose |
+|--------|---------|
+| `stream/` | 4-stage pipeline (Filter → Parse → Monitor → Stall Detect) for 5 agent formats |
+| `pipeline/` | DAG-based phase orchestration — sequential/parallel multi-agent execution |
+| `runner/` | Async subprocess management with stdin/stdout/stderr piping |
+| `registry/` | Agent configurations as data (TOML/dict) with runtime lookup |
+| `config/` | Layered configuration: TOML → env vars → CLI overrides → profiles |
+| `recovery/` | Rate-limit detection, exponential backoff, git dirty-tree recovery |
+| `workspace/` | Artifact lifecycle management |
+| `prompt/` | Jinja2 template rendering with frontmatter stripping |
+| `ui/` | `UICallback` protocol for pluggable display layers |
+| `signals/` | Graceful SIGINT/SIGTERM shutdown |
+| `display/` | Colored stderr logging (no Rich dependency in core) |
+| `observability/` | Optional OpenTelemetry integration |
+
+## Documentation
+
+Full documentation is available at **[abdelazizmoustafa10m.github.io/orchcore](https://abdelazizmoustafa10m.github.io/orchcore/)**.
+
+| Document | Description |
+|----------|-------------|
+| [Installation](doc/getting-started/installation.md) | Prerequisites, install options, extras |
+| [Quick Start](doc/getting-started/quickstart.md) | Define agents, build phases, run pipelines |
+| [Configuration Reference](doc/reference/configuration.md) | Full settings table, profiles, env vars |
+| [Stream Events Reference](doc/reference/stream-events.md) | StreamEvent fields, types, agent states |
+| [UICallback Reference](doc/reference/ui-callback.md) | Protocol methods and built-in implementations |
+| [Architecture](doc/architecture/overview.md) | Package layout, core abstractions, design decisions |
+| [Stream Pipeline](doc/architecture/stream-pipeline.md) | 4-stage composable pipeline deep-dive |
+| [Design Document](doc/architecture/design.md) | Problem statement, requirements, proposed design |
+| [Writing a UICallback](doc/guides/writing-a-uicallback.md) | Build custom display layers |
+| [Agent Registry](doc/guides/agent-registry.md) | TOML config, adding new agents, ToolSets |
+| [Recovery & Retry](doc/guides/recovery-and-retry.md) | Rate limits, backoff, failure modes |
+| [Contributing](doc/development/contributing.md) | Dev setup, code standards, testing |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing instructions, and code standards.
+
+Please also review [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) and [SECURITY.md](SECURITY.md).
+
+## License
+
+orchcore is released under the [MIT License](LICENSE).