# firebase-tools - Doramagic AI Context Pack

> Purpose: pre-work context for the user's host AI. This pack does not prove that the project has been installed, run, or validated.

## Project

- canonical_name: `firebase/firebase-tools`
- capability: Command-Line Interface for Firebase
- expected_user_outcome: Command-Line Interface for Firebase

## Operating Boundaries

- Do not claim that the project has been installed, run, called through an API, or used on local files unless separate evidence proves it.
- Project facts must come from repo evidence, Claim Graph, or explicit source references.
- When a capability is not verified, mark it as unverified instead of completing it as fact.
- publish_status: `publishable`
- blocking_gaps: none

---

## Doramagic Context Augmentation

The following sections strengthen the repository context for a host AI. Human Manual data is a reading route, and pitfall notes become operating constraints.

## Human Manual Outline

Usage rule: this is only a reading route and salience signal, not factual authority. Concrete claims must still return to repo evidence or Claim Graph.

Host AI hard rules:
- Do not treat page titles, section order, summaries, or importance values as factual project evidence.
- When explaining the Human Manual outline, state that it is only a reading route or salience signal.
- Capability, installation, compatibility, runtime state, and risk claims must cite repo evidence, source paths, or Claim Graph.

- **CLI Overview, Configuration, and Authentication**: importance `high`
  - source_paths: README.md, src/index.ts, src/command.ts, src/config.ts, src/rc.ts
- **Deployment Lifecycle and Service Integrations**: importance `high`
  - source_paths: src/deploy/index.ts, src/deploy/lifecycleHooks.ts, src/commands/deploy.ts, src/filterTargets.ts, src/checkValidTargetFilters.ts
- **Emulator Suite, Hosting Server, and Framework Support**: importance `high`
  - source_paths: src/emulator/controller.ts, src/emulator/hub.ts, src/emulator/registry.ts, src/emulator/downloadableEmulators.ts, src/emulator/auth/server.ts
- **MCP Server, AI/Agent Tooling, and Extensions**: importance `high`
  - source_paths: src/mcp/index.ts, src/mcp/server.json, src/mcp/tool.ts, src/mcp/prompt.ts, src/mcp/resource.ts

## Repo Inspection Evidence

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `7f548065abe10b5ad070bfaf8dde064c8e600417`
- inspected_files: `README.md`, `package.json`, `src/getDefaultHostingSite.ts`, `src/agentSkills.ts`, `src/utils.spec.ts`, `src/metapgrogramming.spec.ts`, `src/localFunction.spec.ts`, `src/getProjectNumber.ts`, `src/logError.spec.ts`, `src/getDefaultDatabaseInstance.ts`, `src/rulesDeploy.ts`, `src/functionsConfigClone.ts`, `src/requireConfig.ts`, `src/profiler.ts`, `src/errorOut.spec.ts`, `src/functionsShellCommandAction.ts`, `src/prompt.spec.ts`, `src/projectUtils.ts`, `src/accountExporter.spec.ts`, `src/loadCJSON.ts`

Host AI hard rules:
- Without repo_clone_verified=true, do not claim that the source code has been read.
- Without repo_inspection_verified=true, do not write README, docs, or package-file conclusions as facts.
- Without quick_start_verified=true, do not claim that the Quick Start path has run successfully.

## Doramagic Pitfall Constraints

These rules come from Doramagic discovery, validation, or compilation findings. The host AI must treat them as operating constraints, not background notes.

### Constraint 1: Installation risk requires verification

- Trigger: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | cevd_4f2a1ec2bb424d1686851f68154c4080 | https://github.com/firebase/firebase-tools/issues/10591
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 2: Installation risk requires verification

- Trigger: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | cevd_84267a150a9947d2be48a0fed4c04fba | https://github.com/firebase/firebase-tools/issues/10585
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 3: Security or permission risk requires verification

- Trigger: Developers should check this security_permissions risk before relying on the project: Support loose binding / aliasing for existing GCP Secrets in `defineSecret`
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Support loose binding / aliasing for existing GCP Secrets in `defineSecret`. Context: Observed when using docker
- Why it matters: Developers may expose sensitive permissions or credentials: Support loose binding / aliasing for existing GCP Secrets in `defineSecret`
- Evidence: failure_mode_cluster:github_issue | fmev_99c9e511eabefddccfad471be174c50f | https://github.com/firebase/firebase-tools/issues/10597
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 4: Security or permission risk requires verification

- Trigger: Developers should check this security_permissions risk before relying on the project: functions emulator: "Failed to load function" intermittent failure with no diagnostic information
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: functions emulator: "Failed to load function" intermittent failure with no diagnostic information. Context: Observed when using windows, macos, linux
- Why it matters: Developers may expose sensitive permissions or credentials: functions emulator: "Failed to load function" intermittent failure with no diagnostic information
- Evidence: failure_mode_cluster:github_issue | fmev_441197228e621e13cb5b731e277d1106 | https://github.com/firebase/firebase-tools/issues/10585
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 5: Security or permission risk requires verification

- Trigger: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | cevd_c546fc217e664baa87450621587fee31 | https://github.com/firebase/firebase-tools/issues/10590
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 6: Security or permission risk requires verification

- Trigger: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | cevd_6d785c6692184850a18951f28749620f | https://github.com/firebase/firebase-tools/issues/10597
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 7: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: [cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues. Context: Observed when using linux
- Why it matters: Developers may fail before the first successful local run: [cloud functions for dart] Allow functions in a folder different than "bin" to workaround build hook issues
- Evidence: failure_mode_cluster:github_issue | fmev_caf934975aa33855b8941b352a3e56ef | https://github.com/firebase/firebase-tools/issues/10591
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 8: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: v15.11.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v15.11.0. Context: Observed when using macos
- Why it matters: Upgrade or migration may change expected behavior: v15.11.0
- Evidence: failure_mode_cluster:github_release | fmev_f32bcea39b7c3fc39503955cd4dcec71 | https://github.com/firebase/firebase-tools/releases/tag/v15.11.0
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 9: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: v15.12.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v15.12.0. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v15.12.0
- Evidence: failure_mode_cluster:github_release | fmev_b1e3fdd4c3a2c14194df3ccdd059cdff | https://github.com/firebase/firebase-tools/releases/tag/v15.12.0
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 10: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: v15.18.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v15.18.0. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: v15.18.0
- Evidence: failure_mode_cluster:github_release | fmev_37e78bf4fc82806298e92f88c2607e5f | https://github.com/firebase/firebase-tools/releases/tag/v15.18.0
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.