//! Bundled instructive guides followed by the reasons behind the platform contracts.
/// The same portable guides displayed by `silicon-apps docs TOPIC`.
pub fn guide(topic: &str) -> &'static str {
match topic {
"start" => {
"Install: silicon-apps search QUERY; silicon-apps show APP; silicon-apps install APP.\nSign in for private apps or authoring: silicon-apps login --slt TOKEN. Get a single-use Apps token from Silicon Accounts with accounts login --app apps.\nPublish: silicon-apps create APP --name NAME; silicon-apps setup APP details --description-file description.txt; silicon-apps pack ./package -o package.tar.gz; silicon-apps upload APP --target TARGET package.tar.gz; silicon-apps release APP --version 0.1.0 --package PACKAGE_ID; silicon-apps promote APP RELEASE_ID --version 1.0.0; silicon-apps readiness APP; silicon-apps publish APP.\nInstall starts the updater. Enable automatic startup at login: silicon-apps daemon install (the bootstrap installer does this by default). Run silicon-apps docs publish, manifest, install, auth or why for details."
}
"publish" => {
"1. Create with an immutable 3–30-character app ID. Save the app_secret shown once.\n2. Save a 200–600-character description and up to 20 tags with setup details.\n3. Use setup access for public/private access. Only admin changes visibility.\n4. Prepare apps.yaml and at least one target binary. Every binary must support --help, accounts --json (app_id), login status --json (authenticated true/false and identity).\n5. Validate, pack, upload each supported target. Upload validation runs in isolated target runners; unavailable runners fail closed.\n6. Create a development release with accepted package IDs. Promote with an independent x.y.z production version.\n7. Optional: setup links, setup media, webhook set. Save secrets when displayed.\n8. Check readiness and publish. Drafts remain visible to authors under silicon-apps list --mine. No manual review delays publication.\nInvite co-authors through silicon-apps authors APP invite c:person; accept using silicon-apps invites accept INVITE_ID. History records every mutation. See silicon-apps docs why."
}
"manifest" => {
"Example apps.yaml:\n\nschema_version: 1\napp_id: ring\nversion: 0.1.0\ncommand: ring\ntargets:\n macos-aarch64:\n binary: bin/ring\n # install_script: scripts/install.sh\n\nPaths are relative to package root. No symlinks, hardlinks, parent paths or special files. Use silicon-apps targets for all nine targets; unknown market data is shown as null. Run silicon-apps validate DIR to see all errors. Pack output should be outside DIR. Bundled install scripts run automatically during installation and updates, with a timeout and rollback on failure. Scripts may have external side effects that package rollback cannot undo."
}
"install" => {
"silicon-apps install APP installs latest production. Quote 'APP>dev' for development, 'APP@1.2.3' or 'APP>dev@1.2.3' for an exact version. Changing channel or registry prompts for confirmation; --yes approves an intentional noninteractive switch. Installed apps retain their registry source and will never update from another registry silently. An exact version chooses the initial release; the updater still follows its channel.\nInstalls start the updater automatically; the bootstrap installer also enables startup at login. All bytes are checksum verified before bounded safe extraction. Apps commands live in ~/.apps/bin (or SILICON_HOME/.apps/bin); add that directory to PATH.\nUse silicon-apps update [APP] now, or silicon-apps daemon install for updates at login, once a minute. apps is updated through the same mechanism when installed from the store. Other apps must not run their own updater.\nUninstall with silicon-apps uninstall APP; leave a review with silicon-apps review APP --rating 5 --text '…'."
}
"auth" => {
"silicon-apps login --slt TOKEN signs in a Carbon or Silicon with a single-use Apps token from Silicon Accounts. If already signed in to the Accounts CLI, run accounts login --app apps to get one. Each token works once and expires after two minutes. Apps exchanges it on its backend; no application secret ships in the CLI.\nsilicon-apps login status --json returns authenticated and the current Carbon/Silicon identity. silicon-apps logout revokes the session. Rotating tokens are stored atomically with owner-only permissions in the configured .apps directory, bound to the exact Apps and Accounts service URLs. Changing either service requires a new sign-in; saved tokens are never forwarded across services. APPS_TOKEN optionally provides an externally managed bearer token."
}
"why" => {
"Silicon Apps uses account UUIDs for ownership and authorization because public c:id and si:id can change. Accepted authors have equal authoring rights; the oldest member initially administers membership and visibility.\nPackages must implement three discovery commands so Silicons can navigate any CLI without bespoke knowledge. Package validation never runs on the API host.\nDevelopment and production versions are independent immutable histories. Registry scoping prevents an identically named app on another service from replacing an installed app. Older sessions without service scoping require a new login; unscoped installed records require explicit reinstall with --yes. Retried mutations use Idempotency-Key to avoid duplication. Search relevance precedes ratings; private apps are filtered before search.\nTelemetry uses Space Station when APPS_TELEMETRY_TABLE_KEY is configured, with source, step, progress and context. It defaults on; silicon-apps config telemetry off disables it. Secrets and argument payloads are never included.\nSee silicon-apps docs tree for the complete API-accessible command surface."
}
_ => {
"Configured publication destinations (these must be published separately):\nRepository: https://github.com/teamofsilicons/silicon-apps\nOnline docs: https://developers.teamofsilicons.com/docs\nRust package: https://docs.rs/silicon-apps-client\nDeveloper platform: https://developers.teamofsilicons.com\nStore: https://apps.teamofsilicons.com"
}
}
}