# Clinic API Credential Discovery Guidance Plan

## Background

Clinic system-log investigations can reuse a permission-restricted, environment-specific API-key file under `/private/tmp`. The current agent guidance explains how to create a random temporary file and set `ENV_FILE`, but it does not define a predictable path that an agent must check before reporting that credentials are unavailable. A narrow glob such as `clinic-api.*` also does not match the established `clinic-api-prod.env` filename.

## Goal

Make future production system-log investigations discover, validate, and load `/private/tmp/clinic-api-prod.env` directly before falling back to browser authentication or asking the user to configure a key again.

## Current Behavior

- The `clinic-api` helper defaults `ENV_FILE` to `.env`.
- The guidance creates a randomly named `clinic-api.XXXXXX` file and requires the caller to retain its path in the current shell.
- A new agent shell cannot reliably rediscover that random path.
- No explicit instruction requires checking `/private/tmp/clinic-api-${CLINIC_ENV}.env` before concluding that authentication is unavailable.

## Target Contract

1. Use `CLINIC_API_ENV_FILE` when the caller explicitly provides it.
2. Otherwise check `/private/tmp/clinic-api-${CLINIC_ENV}.env`, including `/private/tmp/clinic-api-prod.env` for production.
3. Before sourcing the file, verify that it is a regular file owned by the current user with mode `600`.
4. Export its exact path as `ENV_FILE`, load the `clinic-api` helper, call `get_clinic_auth`, and verify the datasource catalog.
5. Never print or inspect the key value.
6. Only report missing credentials or fall back to browser authentication after the explicit and conventional paths have been checked.

## Affected Files

- `AGENTS.md`: credential discovery and loading instructions for Clinic system logs.
- This dated implementation plan.
- `docs/clinic-module-overview.md` remains accurate because no module, executable, image, workflow, or deployment mapping changes.

## Implementation

1. Add an explicit existing-file discovery block before the key-creation instructions.
2. Document the stable per-environment `/private/tmp/clinic-api-${CLINIC_ENV}.env` convention.
3. Include macOS and Linux ownership/mode checks without exposing file contents.
4. Update the creation example to use the same predictable path.
5. Require successful `get_clinic_auth` and datasource-catalog validation before log queries.
6. Explain that broad or mismatched filename globs are not a substitute for checking the exact conventional path.

## Exclusions

- Do not change Clinic application code, APIs, authentication behavior, or the `clinic-api` helper.
- Do not add credentials or credential files to the repository.
- Do not modify app-delivery, Kubernetes resources, or runtime configuration.
- Do not deploy or release any component.

## Compatibility and Security

The guidance remains compatible with an explicitly supplied `CLINIC_API_ENV_FILE` and with interactive creation when no reusable file exists. The stable file is accepted only when it belongs to the current user and has mode `600`. Key contents must never be printed, searched, logged, or committed.

## Validation

- Confirm `/private/tmp/clinic-api-prod.env` is discovered when present with mode `600`.
- Confirm a missing file does not cause a broad secret search.
- Confirm an unsafe owner or mode fails before the file is sourced.
- Confirm `ENV_FILE` is exported before `get_clinic_auth` and the datasource catalog succeeds.
- Run `git diff --check`.
- Confirm the tracked diff contains only `AGENTS.md` and this plan.

## Release Boundary

Required deployment modules: none. This is documentation-only guidance. Commit, push, pull request creation, merge, and release remain separate authorization boundaries.