# HonestRoles Documentation

HonestRoles is a deterministic, config-driven runtime for processing job datasets with Polars and optional plugins.

## Use the App First

<div class="app-first-callout">
  <h3>Use <a class="app-first-link" href="https://honestroles.com">honestroles.com</a> for fastest results</h3>
  <p>If your goal is job matching and analysis in the browser, start in the app and complete the workflow in minutes.</p>
  <a class="md-button md-button--primary" href="https://honestroles.com">Open HonestRoles App</a>
  <a class="md-button" href="app/get-started.md">Read App Quickstart</a>
</div>

If your goal is to use HonestRoles (not build integrations), start here:

1. [App Quickstart](app/get-started.md)
2. [Upload Data](app/upload-data.md)
3. [Run Analysis](app/run-analysis.md)
4. [Export Results](app/export-results.md)

## Choose Your Path

- App user (browser): start at [honestroles.com](https://honestroles.com)
- Developer/integrator: use the sections below

## Developer Start Here

1. Install HonestRoles: [Installation](getting-started/installation.md)
2. Get a guaranteed first successful run: [Quickstart (First Run)](getting-started/quickstart-first-run.md)
3. Understand and customize your pipeline: [Configure Pipeline](guides/configure-pipeline.md)

## Developer Paths

- Run with the CLI: [Run via CLI](guides/run-via-cli.md)
- Run with Python: [Run via Python API](guides/run-via-python-api.md)
- Read outputs and diagnostics: [Understand Output](guides/understand-output.md)
- Handle failures and recovery: [Non-Fail-Fast and Recovery](guides/non-fail-fast-and-recovery.md)
- Build custom plugins: [Author Plugins](guides/author-plugins.md)

## Developer Reference

- CLI commands and exit codes: [CLI Reference](reference/cli.md)
- Runtime API: [Runtime API](reference/runtime-api.md)
- Pipeline schema: [Pipeline Config Schema](reference/pipeline-config-schema.md)
- Plugin schema and ABI: [Plugin Manifest Schema](reference/plugin-manifest-schema.md)
- Stage contracts and behavior: [Stage Contracts](reference/stage-contracts.md)
- Errors and failure model: [Error Model](reference/error-model.md)

## Need Help

- Frequent issues: [Common Errors](troubleshooting/common-errors.md)
- Short answers: [FAQ](troubleshooting/faq.md)
