docs(auto-activation): add auto-activation concept page and man pages (DEV-89) by djsauble · Pull Request #31 · flox/docs

djsauble · 2026-06-18T18:13:53Z

Summary

Documents the experimental auto-activation feature on the docs site
(DEV-89).
Auto-activation activates an environment when you cd into a directory that
contains it and deactivates it when you leave.

Written against the actual implementation at the top of the auto-activate
stack — this supersedes the earlier exploration in
flox/floxdocs#456, whose behavior
had diverged (and which lived in the now-stale floxdocs repo).

Changes (hand-authored content only)

New concepts/auto-activation.mdx: enablement (the BETA auto_activate
feature flag plus the prompt hook installed by an in-place activation),
how the hook works, the allow/deny consent flow, nested environments,
deactivation/layer-peeling, and a comparison with manual activation.
Cross-link from concepts/activation.mdx.
One docs.json nav entry for the new concept page.

Man pages are out of scope here

Per review, the man/*.mdx changes and their docs.json nav entries were
removed — those are generated from the flox/flox sources via
scripts/sync-man-pages.sh and should land via that sync (the auto-activation
man pages come from flox/flox#4407). I confirmed docs.json is not
auto-updated by the sync, so the concept-page nav entry is added here by hand.

Ordering note 👀

The concept page links to /man/flox-activate-allow and
/man/flox-activate-deny, which don't exist until the man pages are synced from
flox/flox#4407. Merge after that sync so mint broken-links is clean.

…DEV-89) - New concepts/auto-activation.mdx covering enablement (the BETA feature flag plus the prompt hook), the allow/deny consent flow, nested environments, and deactivation, written against the actual implementation. - Cross-link to it from concepts/activation.mdx. - Regenerate man/flox-activate and man/flox-config and add man/flox-activate-allow and man/flox-activate-deny, synced from the flox/flox man-page sources. - Add the new pages to the docs.json navigation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

mintlify · 2026-06-18T18:15:11Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
flox	🟢 Ready	View Preview	Jun 18, 2026, 6:15 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

djsauble

~~Let's also add a line to the AGENTS.md in this repository that man pages shouldn't be edited directly in this repository since they're automatically synced from the flox/flox repo.~~

this is already documented under the "Man pages are generated — do not edit directly" section:

Everything under man/ is generated from the man page sources in the flox/flox repo (cli/flox/doc/*.md).

Do not edit man/*.mdx directly — changes will be overwritten by the next sync.

To fix or update a man page, edit the source in flox/flox (cli/flox/doc/), then regenerate: ./scripts/sync-man-pages.sh <path-to-flox-repo> ./man

New pages also need a navigation entry in docs.json under the "CLI reference" tab.

Man pages under man/ are generated from flox/flox via sync-man-pages.sh, so they (and their docs.json "CLI reference" entries) land with that sync rather than this PR. The auto-activation man pages come from flox/flox#4407. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

These man pages are synced from flox/flox; their nav entries belong with that sync. The hand-authored concepts/auto-activation entry stays. docs.json is not auto-updated by the sync, so nav entries are maintained by hand (see AGENTS.md). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tanjadev · 2026-06-23T13:54:25Z

+  enabling and disabling the flag is enough to turn auto-activation on and off.
+</Note>
+
+## How it works


Love that we're explaining this here!

tanjadev · 2026-06-23T13:54:48Z

+4. **Deactivation** — When you leave a directory, its environment is deactivated
+   and its changes to the shell are reverted.
+
+Most prompts hit a fast path: the hook detects that nothing relevant has changed


praise: good to mention it right away!

Co-authored-by: tanjadev <tanja@floxdev.com>

…ature flag (DEV-89) (flox#4407) ## Summary Documents the experimental **auto-activation** feature in the man pages ([DEV-89](https://linear.app/floxdotdev/issue/DEV-89/update-auto-activate-docs-man-pages)). Auto-activation activates an environment when you `cd` into a directory that contains it and deactivates it when you leave. The docs are written against the **actual implementation** at the top of the auto-activate stack (`daniel/dev-132-…`), not the older prototype on `feat/auto-activation`, whose behavior has since diverged. ### Changes - **New** `flox-activate-allow(1)` and `flox-activate-deny(1)` pages for the `flox activate allow` / `flox activate deny` subcommands. - **New** `AUTO-ACTIVATION` section in `flox-activate(1)` covering the prompt hook, the interactive consent prompt, the allow/deny flow, and how to enable the feature. - `flox-config(1)`: documents `auto_activate` (`prompt`/`allowed`, default `prompt`), `auto_activate_environments`, `auto_activate_fish_mode`, `features.auto_activate`, and the `FLOX_FEATURES_AUTO_ACTIVATE` env var; ties `disable_hook` to auto-activation. - **New** shared include `include/auto-activate-experimental.md` carrying the "experimental + how to enable" note. - Promotes the staged `doc-auto-activate/flox-config.md` into the shipped `flox-config(1)` and removes the staging copy. ### How to enable (BETA), as documented 1. Install the prompt hook via any in-place activation in your shell rc, e.g. `eval "$(flox activate -D)"` (registration is gated only by `disable_hook`). 2. Set the feature flag: `FLOX_FEATURES_AUTO_ACTIVATE=true` or `flox config --set features.auto_activate true`. ## Decisions to confirm 👀 - **Promote to shipped man pages vs. keep staging.** I moved the auto-activate docs into the real `cli/flox/doc/` man pages (which the Nix build ships) and deleted the unshipped `doc-auto-activate/` staging copy, each marked experimental with enablement notes. If you'd rather keep these staged until the feature is GA, say so and I'll move them back. - **Based off `main`.** The man-page sources are pure markdown with no build dependency on the Rust code, so this is based on `main`. It should merge only once the auto-activation feature itself has landed. - No `## Release Notes` section: the documented feature is behind a feature flag and marked experimental. ## Paired docs PR Companion changes to the docs site (`flox/docs`) — concept page + regenerated man-page MDX — are in flox/docs#31 (flox/docs#31). Verified: all four pages compile with `pandoc` + the repo's man-page filters; includes expand correctly.

djsauble mentioned this pull request Jun 18, 2026

docs(activate): document auto-activation, allow/deny, and the BETA feature flag (DEV-89) flox/flox#4407

Merged

mintlify Bot deployed to staging June 18, 2026 18:15 View deployment

djsauble self-assigned this Jun 18, 2026

djsauble commented Jun 18, 2026

View reviewed changes

djsauble and others added 7 commits June 18, 2026 13:31

docs(auto-activation): drop the redundant supported-shells line

75c93e8

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(auto-activation): allow/deny only accept the -d selector

c9cab4e

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(auto-activation): use the -d form in the deny example

d6d415d

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(auto-activation): clarify deactivation in the comparison table

93f273f

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(auto-activation): note hierarchy activation in the comparison table

5dbf1a5

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

mintlify Bot deployed to staging June 18, 2026 20:34 View deployment

djsauble marked this pull request as ready for review June 18, 2026 20:44

djsauble requested a review from stephenyeargin June 18, 2026 22:24

tanjadev approved these changes Jun 23, 2026

View reviewed changes

stephenyeargin approved these changes Jun 23, 2026

View reviewed changes

fix: update concepts/auto-activation.mdx

538f957

Co-authored-by: tanjadev <tanja@floxdev.com>

mintlify Bot deployed to staging June 25, 2026 16:20 View deployment

stephenyeargin approved these changes Jun 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(auto-activation): add auto-activation concept page and man pages (DEV-89)#31

docs(auto-activation): add auto-activation concept page and man pages (DEV-89)#31
djsauble wants to merge 9 commits into
mainfrom
daniel/dev-89-update-auto-activate-docs-man-pages

djsauble commented Jun 18, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

djsauble left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tanjadev Jun 23, 2026

Uh oh!

tanjadev Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

djsauble commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes (hand-authored content only)

Man pages are out of scope here

Ordering note 👀

Uh oh!

mintlify Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

djsauble left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tanjadev Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

tanjadev Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

djsauble commented Jun 18, 2026 •

edited

Loading

mintlify Bot commented Jun 18, 2026 •

edited

Loading

djsauble left a comment •

edited

Loading