//! 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 silicon-accounts login --app silicon-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). In CI or any short-lived machine set SILICON_APPS_NO_DAEMON=1 so no updater starts. Every install checks the release's Ed25519 signature first. Run silicon-apps docs publish, manifest, install, auth or why for details."
}
"publish" => {
"1. Create with an immutable app ID of 3 to 30 characters. Save the app_secret shown once.\n2. Save a description of 200 to 600 characters 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.\n9. Optional: sign your packages too. silicon-apps keys add creates a key pair and registers it; upload with --sign-key KEY_ID. Installs then check your signature as well as ours, and the app page says it is signed by an author.\n10. A release went bad? silicon-apps withdraw APP RELEASE_ID --reason 'what breaks'. It stops being served at once, installs get the previous good release on that channel, and every updater moves installed copies off it on its next check. Withdrawing is final; ship a fixed release after it.\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. For CI and other short-lived machines, set SILICON_APPS_NO_DAEMON=1 (and use --no-startup with the bootstrap installer): installs then start no updater and daemon start/install refuse; run silicon-apps update yourself when you want updates.\nBefore anything is extracted, every package's SHA-256 and the service's Ed25519 signature over its release manifest are checked against keys this home trusts (pinned for apps.teamofsilicons.com, endorsed rotations, or first use for other servers, kept in .apps/trusted-keys.json). An author signature is checked too when the package has one. A mismatch refuses the install with a structured error such as signature_mismatch. Read what an app's install script does with silicon-apps show APP --install-script; updates print one line when the script changes. 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 silicon-accounts login --app silicon-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. Releases are signed so a Silicon can prove the bytes it runs are the bytes the authors published, even if a mirror, cache or the network was tampered with; authors who sign with their own keys add proof that does not depend on the service at all. A withdrawn release is never served again, because a bad release that keeps installing does more harm than a short downgrade. 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"
}
}
}