# slskr Documentation

This index is the maintained map for repository docs. The root
[README](../README.md) is the project overview; this file is the table of
contents for operators, API users, UI contributors, release work, and parity
audits.

## Start Here

| Document | Use it for |
| --- | --- |
| [Project README](../README.md) | Product overview, screenshots, quick start, feature summary, and top-level links. |
| [Getting started](getting-started.md) | First run from a release archive through login, shares, and a first search. |
| [Feature map](FEATURES.md) | User-facing map of current slskR feature areas. |
| [Feature guides](features/README.md) | Per-area guides for search, transfers, shares, messaging, media, integrations, mesh, API, operations, security, and localization. |
| [Status and support boundaries](status.md) | Which behavior is ordinary, configured, compatibility-only, or limited. |
| [Configuration guide](configuration.md) | Config sources, network defaults, credentials, and optional features. |
| [Troubleshooting](troubleshooting.md) | Common operator problems and focused checks. |
| [Localization roadmap](localization-roadmap.md) | Language coverage, regional preferences, and the next translation batches. |
| [Install guide](install.md) | Build, install, service, container, config, state, and exposure runbook. |
| [Credential storage](credential-storage.md) | Soulseek credential-source choices, systemd credentials, Web UI behavior, and security notes. |
| [OpenID Connect sign-in](oidc-authentication.md) | Provider setup, exact callback and reverse-proxy base path, verified-email admission, controller-admin session behavior, recovery, Apple setup, and troubleshooting. |
| [Setup experience contract](design/setup-experience-contract.md) | How first-use credential entry, sharing, connection status, and optional integrations should build on the existing Web UI. |
| [Config example](slskr.config.example.toml) | Annotated TOML config with the supported runtime settings. |
| [Gold Star Club](gold-star-club.md) | Purpose, lifecycle, membership policy, and opt-in/opt-out configuration. |
| [App surface](app-surface.md) | User-facing CLI, daemon, API, Web UI, auth, and compatibility surface. |

## Feature Guides

| Area | Guide |
| --- | --- |
| Feature index | [features/README.md](features/README.md) |
| Search and discovery | [features/search-and-discovery.md](features/search-and-discovery.md) |
| Transfers | [features/transfers.md](features/transfers.md) |
| Shares and browse | [features/shares-and-browse.md](features/shares-and-browse.md) |
| Messaging, rooms, and users | [features/messaging-rooms-users.md](features/messaging-rooms-users.md) |
| Web UI and media | [features/web-ui-and-media.md](features/web-ui-and-media.md) |
| Integrations | [features/integrations.md](features/integrations.md) |
| Mesh, DHT, and pods | [features/mesh-dht-pods.md](features/mesh-dht-pods.md) |
| API and automation | [features/api-and-automation.md](features/api-and-automation.md) |
| Data and operations | [features/data-and-operations.md](features/data-and-operations.md) |
| Security and access | [features/security-and-access.md](features/security-and-access.md) |
| Localization | [features/localization.md](features/localization.md) |

## Web UI

| Document | Use it for |
| --- | --- |
| [Web UI README](../web/README.md) | React/Vite Web UI development, audit, build, and screenshot workflow. |
| [README screenshots](screenshots/) | Generated screenshots used by the root README. |
| [Web UI endpoint inventory](webui-endpoints.txt) | Route inventory used during parity and audit work. |
| [Rust Web UI notes](rust-web-ui.md) | Rust/WASM migration target notes; not the currently shipped browser bundle. |
| [Rust UI parity ledger](rust-ui-parity-ledger.md) | UI parity and migration audit ledger. |

## Architecture

| Document | Use it for |
| --- | --- |
| [Architecture and network layout](architecture.md) | Daemon components, state ownership, and the native/current shared peer port. |
| [App surface](app-surface.md) | CLI, daemon, API, Web UI, auth, and compatibility details. |

The currently shipped browser UI is the React/Vite app in `web/`. Release
archives package the built assets and `slskr serve` serves them on the same
listener as the HTTP API.

## HTTP API And Automation

| Document | Use it for |
| --- | --- |
| [HTTP API reference](http-api.md) | Maintained route reference and request/response examples. |
| [HTTP API features](http-api-features.md) | Capability notes, event stream details, and workflow examples. |
| [HTTP API deployment](http-api-deployment.md) | Auth, reverse proxy, exposure, and Kubernetes deployment notes. |
| [OpenAPI document](openapi.json) | Machine-readable API contract. |
| [Webhook API](WEBHOOK_API.md) | Webhook subscription, delivery, signing, and retry behavior. |
| [Client libraries](CLIENT_LIBRARIES.md) | Cross-language SDK overview. |
| [TypeScript client](../client-ts/README.md) | `@slskr/api-client` usage. |
| [Python client](../client-python/README.md) | Python client usage. |
| [Go client](../client-go/README.md) | Go client usage. |
| [Examples](../examples/README.md) | End-to-end API and automation examples. |
| [GraphQL schema](GRAPHQL_SCHEMA.graphql) | GraphQL contract notes for integration surfaces. |

Unless a document says otherwise, local examples assume the default daemon URL:

```text
http://127.0.0.1:5030
```

## Operations, Release, And Security

| Document | Use it for |
| --- | --- |
| [Release guide](release.md) | Tag, archive, manifest, checksum, and verification policy. |
| [Status and support boundaries](status.md) | Product capability and compatibility limits. |
| [Live interop matrix](live-interop-test-matrix.md) | Live Soulseek-network and cross-client verification gates. |
| [VPN certification](vpn-certification.md) | Per-account VPN isolation, credential pool setup, and certification runner. |
| [Full network test plan](full-network-test-plan.md) | Test phases, pass criteria, and release-readiness certification plan. |
| [Security bug burndown](security-bug-burndown.md) | Security audit findings and remediation status. |
| [Compliance](../COMPLIANCE.md) | Project compliance and public posture notes. |
| [Remediation plan](../REMEDIATION.md) | Historical remediation tracking. |
| [Project plan](../PLAN.md) | Planning notes and backlog context. |
| [GitHub Actions pin policy](dev/github-actions-pin-policy.md) | CI action pinning policy. |
| [Rust dependency hygiene](dev/rust-dependency-hygiene.md) | Rust dependency review guidance. |

## Fixtures, Parity, And Performance

| Document | Use it for |
| --- | --- |
| [Open commons fixtures](open-commons-fixtures.md) | Fixture source policy and manifest notes. |
| [Legacy port harvest](legacy-port-harvest.md) | Historical implementation and parity harvest notes. |
| [Runtime parity ledger](parity/slskdn-slsknet-runtime-parity.md) | slskdN/Soulseek.NET-family behavior parity ledger. |
| [Performance analysis](performance-analysis.md) | Performance observations and follow-up areas. |
| [Idle container benchmark](../benchmarks/artifacts/20261012-idle-container-slskr-slskd.md) | Repeated pinned-image CPU/RSS matrix: matched disconnected slskR/slskd and DHT-on slskR, with raw data and method limits. |
| [Live Soulseek idle benchmark](../benchmarks/artifacts/20261012-live-soulseek-idle.md) | Connected-idle comparison of slskd, slskR with DHT off, and slskR with DHT on on `kspld0`, plus the aborted `kspls0` attempt and host-load evidence. |
| [Enhancements](ENHANCEMENTS.md) | Historical enhancement backlog. |
| [Integration guide](INTEGRATION_GUIDE.md) | Historical component-integration backlog; use current API and Web UI docs for runbooks. |

## Developer Audit Notes

The `docs/dev/` directory holds audit ledgers and internal review playbooks:

| Document | Use it for |
| --- | --- |
| [Refactor and efficiency plan](dev/refactoring-efficiency-plan.md) | Living whole-project refactor backlog and execution status. |
| [Whole-project refactor audit](dev/refactor-audit-20260915.md) | Evidence snapshot, findings, priorities, and validation requirements from the 2026-09-15 review. |
| [Refactor handoff](dev/refactor-handoff-20260915.md) | Current dirty-worktree handoff, validation baseline, residual work, and safe resume procedure. |

## Documentation Status

- The canonical operator entry points are the root README, this index,
  [getting-started.md](getting-started.md), [install.md](install.md),
  [configuration.md](configuration.md), [status.md](status.md),
  [troubleshooting.md](troubleshooting.md), [app-surface.md](app-surface.md),
  and [http-api.md](http-api.md).
- The shipped Web UI is documented in [../web/README.md](../web/README.md).
  Rust/WASM UI docs are retained as migration notes until that target replaces
  the React bundle.
- Historical planning documents are retained because they explain why surfaces
  exist, but they are not deployment runbooks unless this index marks them as
  maintained operator docs.