[ClaydeCode]

Closes #7.

Documents the secret('<name>') helper that compose templates gained in FreeshardBase/freeshard#173. Until now docker_compose_template.md did not mention it. Note that the syntax is a function call, {{ secret('db_password') }}. The {{ secret.my-secret }} form in #7 was written before the implementation and does not work.

Changes

• New ### Secrets section under Variables. It is prose plus a short snippet, not a template_vars_*.md include table. secret() is a function with a free-form name, so a table would hold one row with no real example value.
• Complex example: the redis is now password-protected. The app gets REDIS_PASSWORD={{ secret('redis_password') }} and redis gets --requirepass with the same call, which shows that one name gives the same value in both containers. Annotations renumbered from 6 onward.
• digest.md (the AI-optimized digest that the landing page's llms.txt and the app-repository add-app skill point at): same example change plus a terse secrets block, Generated: stamped 2026-11-03. No other file under docs/ has changed since the previous generation on 2026-06-29, so the digest is now fully current. Split digest.md into a product and an app-dev digest, and enforce freshness in CI #17 (CI freshness check) is still needed to keep it that way.

How the behaviour was verified

Every claim comes from the shard_core source, not from memory: app_secrets.py, render_docker_compose_template in util.py, database/app_secrets.py, migration shard-core-0006, tests/test_app_secrets.py and the "App compose template context" section of shard_core's agents.md:

• Value: 32 characters from [A-Za-z0-9], generated on the first render that references the name.
• Reuse: the same value comes back for the same name on later renders, app updates, restarts and reinstalls. It is never rotated.
• Scope: per app. Kept on uninstall. Included in the DB snapshot backup.
• Availability: from 0.41.3. The code is first in the 0.41.2 tag (I checked util.py at each tag: 0.41.0 and 0.41.1 have no secret= in the render call), but 0.41.2's image was never published (ghcr.io manifest is a 404; flaky CI test, fixed in tests: mock the real docker-prune subprocess in test_docker_prune freeshard#263), so 0.41.3 is the first version a shard can run. As of 2026-11-03 it is not yet rolled out to the fleet, so consider merging this after that rollout. Drop the version line if all shards are assumed to be current.

mkdocs build --strict passes locally.

Related, not addressed here

• Cross-app isolation of secrets (the template renders unsandboxed) is deliberately left out of the docs. It is tracked in App secrets are not isolated between apps: compose template renders unsandboxed freeshard#264.
• oidc template context: also undocumented on this page. Tracked in Document the OIDC app integration: the app_meta oidc block and {{ oidc.* }} template vars (follow-up to freeshard#148/#149) #15.

🤖 Generated with Claude Code