docs

Table Of Contents

1. Using These Docs
   1. What Lives Here
   2. Reading Map
   3. Repository Terms

1. Using These Docs

What Lives Here

This directory is the long-form manual for AppRC. The root README stays short enough for package discovery and first integration. These files hold task recipes, exact reference names, system explanations, and maintainer workflow.

Fig. 1 - Documentation Reading Map: Start at the root README, then move into the docs file that matches the job: recipe, maintainer workflow, exact names, or system model.

Note

Related: use How-To User Guides for commands in order, References for exact names, and Explanations for why AppRC behaves as it does.

Reading Map

• How-To User Guides: recipes for integrating AppRC into an app, setting up storage, editing values, and diagnosing setup.
• Explanations: the system model behind config sections, capability layers, bootstrap, storage selection, provenance, CLI, and TUI.
• References: exact public imports, constructor modes, CLI commands, env vars, filenames, precedence rules, and status names.
• Development: maintainer workflow, documentation generation, local verification, and repo-specific documentation rules.

Recommended reading paths:

Goal	Start Here	Then Read
Add AppRC to an app	README	How-To User Guides
Understand the design	Explanations	References
Debug a user's setup	How-To User Guides	Doctor Statuses
Check an exact API name	References	Source files linked from that section
Change this repo	Development	AGENTS.md

Note

Related links:

• Use Development: documentation rules before changing docs structure or callout/link conventions.
• Use References: documentation assets before changing documentation figures.

Repository Terms

Use these terms consistently in every docs file:

Term	Meaning	Main Reference
AppRC	This package, apprc, which supplies runtime config, generated config CLI, and Textual editor helpers.	System Model
application	The downstream Python app that integrates AppRC.	Integration Flow
config contract	The rc.Config and rc.ConfigBase classes registered on one rc.AppRC facade.	Config Contract Model
registered config	A related group of settings declared with @MyRC.config(...).	Public Interfaces
config field	One typed setting declared with rc.field("FULL_ENV_KEY", ...).	Public Interfaces
capability layer	A persistence feature selected by the rc.AppRC constructor.	Capability Constructors
app-wide dotenv	The per-user .env.apprc-app file below the platform config home.	Configuration Files
storage dotenv	The .env.apprc-storage file inside one selected storage root.	Configuration Files
named-storage index	The optional <app>.apprc.toml registry for named storage roots.	Storage Selection
zero-write read	A command or runtime operation that inspects config without creating files.	Zero-Write Policy