# encore - Doramagic AI Context Pack > Positioning: a pre-install experience and judgment asset. It helps the host AI get off to a good start, but it does not mean the project has already been installed, run, or validated. ## Sufficiency Principle - **Sufficiency over compression**: The AI Context Pack should be sufficient for the host AI to understand the project's value, capability boundaries, entrypoints, risks, and evidence sources before starting work; it may be layered, but it does not aim for the shortest possible summary. - **Compression policy**: Compress only noise and duplication, never context that affects judgment or the quality of the work. ## How the Host AI Should Use This You are reading the AI Context Pack that Doramagic compiled for encore. Treat it as pre-work context: help the user understand who it fits, what it can do, how to start, what must be verified after install, and where the risks are. Do not claim that you have already installed, run, or executed the target project. ## Claim Consumption Rules - **Fact source**: Repo Evidence + Claim/Evidence Graph; the Human Wiki only supplies salience, terminology, and narrative structure. - **Minimum status for a fact**: `supported` - `supported`: May be used as a project fact, but the answer must cite the claim_id and evidence path. - `weak`: Usable only as a low-confidence lead; the user must be asked to keep verifying. - `inferred`: Usable only for risk notes or open questions; must not be packaged as a project fact. - `unverified`: Must not be used as fact; state clearly that evidence is insufficient. - `contradicted`: Must show the conflicting sources and must not force a single version on the user's behalf. ## Who It Fits Best - **Developers already using host AIs such as Claude/Codex/Cursor/Gemini**: The README or plugin config mentions multiple host AIs. Evidence: `README.md` Claim: `clm_0002` supported 0.86 ## What It Can Do - **Command-Line Startup or Install Flow** (Verify after install): The project documentation contains runnable commands; real use requires running them in a local or host environment. Evidence: `.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` et al. Claim: `clm_0001` supported 0.86 ## How to Start - `curl -X PUT --data-binary @/home/me/dog-wizard.jpeg "https://storage.googleapis.com/profile-pictures/my-user-id/?x-goog-signature=b7a1<...>"` Evidence: `docs/go/primitives/object-storage.md` Claim: `clm_0003` unverified 0.25 - `curl https://myapp.ondigitalocean.app/hello/world` Evidence: `docs/go/self-host/deploy-to-digital-ocean-wip.md` Claim: `clm_0004` unverified 0.25 - `curl https://myapp.ondigitalocean.app/names/1` Evidence: `docs/go/self-host/deploy-to-digital-ocean-wip.md` Claim: `clm_0005` unverified 0.25 - `curl -d '{` Evidence: `docs/go/tutorials/incident-management-tool.md` Claim: `clm_0006` unverified 0.25, `clm_0012` unverified 0.25 - `curl -X PUT "http://localhost:4000/incidents/1/acknowledge"` Evidence: `docs/go/tutorials/incident-management-tool.md` Claim: `clm_0007` unverified 0.25 - `npx add-skill encoredev/skills` Evidence: `docs/go/ai-integration.md` Claim: `clm_0008` supported 0.86, `clm_0009` supported 0.86, `clm_0010` supported 0.86 - `npx add-skill encoredev/skills --list` Evidence: `docs/go/ai-integration.md` Claim: `clm_0009` supported 0.86 - `npx add-skill encoredev/skills -a cursor -a claude-code` Evidence: `docs/go/ai-integration.md` Claim: `clm_0010` supported 0.86 - `claude mcp add --transport stdio encore-local -- encore mcp run --app=your-app-id` Evidence: `docs/go/ai-integration.md` Claim: `clm_0011` supported 0.86 - `curl -d "client_id=${OAUTH_CLIENT_ID}" -d "client_secret=${OAUTH_CLIENT_SECRET}" \` Evidence: `docs/platform/integrations/oauth-clients.md` Claim: `clm_0012` unverified 0.25 ## Continue-or-Stop Decision Card - **Current recommendation**: Trial role matching first - **Why**: This project is more of a role library; the core risk is picking the wrong role or treating role copy as execution capability. Trial role matching with Prompt Preview first, then decide whether to sandbox-import it. ### 30-Second Read - **What to do now**: Trial role matching first - **Minimum safe next step**: Trial role matching with Prompt Preview first; import in isolation only once satisfied - **Do not trust yet**: Role quality and task fit cannot be trusted directly. - **Continuing will touch**: Role selection bias, Command execution, Local environment or project files ### What You Can Trust Now - **Target-audience signal: Developers already using host AIs such as Claude/Codex/Cursor/Gemini** (supported): Backed by a supported claim or project evidence, but that still is not the same as real install results. Evidence: `README.md` Claim: `clm_0002` supported 0.86 - **Capability exists: Command-Line Startup or Install Flow** (supported): You can trust that the project contains signals of this capability; whether it fits your specific task still needs trial or after-install verification. Evidence: `.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` et al. Claim: `clm_0001` supported 0.86 - **There are Quick Start / install-command signals** (supported): You can trust that the docs mention a startup or install entrypoint; do not run it directly in your primary environment because of that. Evidence: `docs/go/ai-integration.md` Claim: `clm_0008` supported 0.86, `clm_0009` supported 0.86, `clm_0010` supported 0.86 ### What You Cannot Trust Yet - **Role quality and task fit cannot be trusted directly.** (unverified): A role library proves there are many roles; it does not prove each one fits your specific task or that a role produces high-quality results. - **Do not treat role copy as real execution capability.** (unverified): Before install you can only judge whether the role description and task profile match; you cannot prove it can complete the task inside the host AI. - **Real output quality cannot be trusted before install.** (unverified): Prompt Preview can only show how it guides you; it cannot prove result quality in the real project. - **Host AI version compatibility cannot be trusted before install.** (unverified): Host loading rules and version differences across Claude, Cursor, Codex, Gemini, and others must be verified in a real environment. - **That it will not pollute your existing host AI's behavior cannot be trusted directly.** (inferred): Skill, plugin, and AGENTS/CLAUDE/GEMINI instructions may change the host AI's default behavior. - **Safe rollback cannot be assumed by default.** (unverified): Unless the project clearly provides uninstall and recovery instructions, verify in an isolated environment first. - **After a real install, is it compatible with the user's current host AI version?** (unverified): Compatibility can only be verified in the actual host environment. - **Does the project's output quality meet the user's specific task?** (unverified): The pre-install preview can only show flow and boundaries; it cannot replace real evaluation. ### What Continuing Will Touch - **Role selection bias**: The user's judgment about which expert role should handle the task. Why: Picking the wrong role makes the AI answer from the wrong expert perspective, wasting time or misleading decisions. - **Command execution**: Package managers, network downloads, the local plugin directory, project config, or the user's home directory. Why: Running the very first command can already change your environment; decide whether it is worth running first. Evidence: `.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` et al. - **Local environment or project files**: Install results, plugin caches, project config, or local dependency directories. Why: The write scope and rollback path cannot be proven before install and need isolated verification. Evidence: `.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` et al. - **Host AI context**: The AI Context Pack, Prompt Preview, Skill routing, risk rules, and project facts. Why: Importing context affects the host AI's later judgment, so avoid packaging unverified items as facts. ### Minimum Safe Next Steps - **Run Prompt Preview first**: Use an interactive trial to verify the task profile and role match first; do not import the whole role library up front. (applies when: Applies to any project, especially when output quality is unknown.) - **Trial-install only in an isolated directory or a test account**: Avoid letting install commands pollute your primary host AI, real projects, or home directory. (applies when: When there are signals of command execution, plugin config, or local writes.) - **After install, verify just one minimal task**: Verify loading, compatibility, output quality, and rollback first, then decide whether to use it deeply. (applies when: When moving from a trial into a real workflow.) ### Exit Plan - **Preserve the pre-install state**: Record the original host config and project state so you can later judge whether it is recoverable. - **Keep a record of the original role selection**: If output goes off-topic, you can return to the task-profiling stage and reselect a role instead of pushing on with the wrong one. - **Record the install commands and written paths**: Without clear uninstall instructions, you at least need to know which directories or configs to clean up manually. - **If there is no rollback path, do not enter your primary environment**: No rollback is a blocker before continuing; do not proceed on trust or luck. ## What Can Only Be Previewed - Explain who the project fits and what it can do - Demonstrate a typical conversation flow based on project docs - Help the user decide whether it is worth installing or researching further ## What Must Be Verified After Install - Actually installing the Skill, plugin, or CLI - Running scripts, modifying local files, or accessing external services - Verifying real output quality, performance, and compatibility ## Boundary & Risk Decision Card - **Mistaking the pre-install preview for a real run**: The user may overestimate how much configuration, permission, and compatibility verification the project has already done. Mitigation: Clearly separate prompt_preview_can_do from runtime_required. Claim: `clm_0025` inferred 0.45 - **Command execution will modify the local environment**: Install commands may write to the user's home directory, the host plugin directory, or project configuration. Mitigation: Run in an isolated environment or a test account first. Evidence: `.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` et al. Claim: `clm_0026` supported 0.86 - **To confirm**: After a real install, is it compatible with the user's current host AI version?. Why: Compatibility can only be verified in the actual host environment. - **To confirm**: Does the project's output quality meet the user's specific task?. Why: The pre-install preview can only show flow and boundaries; it cannot replace real evaluation. - **To confirm**: Do the install commands require network access, permissions, or global writes?. Why: This affects install risk in both enterprise and personal environments. ## Pre-Work Working Context ### Loading Order - First read how_to_use.host_ai_instruction to establish the boundaries of this pre-install judgment asset. - Read claim_graph_summary to confirm facts come from the Claim/Evidence Graph, not the Human Wiki narrative. - Then read intended_users, capabilities, and quick_start_candidates to judge whether the user is a match. - When you need to carry out a concrete task, check role_skill_index first, then evidence_index. - For real install, file modification, network access, performance, or compatibility questions, turn to risk_card and boundaries.runtime_required. ### Task Routes - **Command-Line Startup or Install Flow**: State that this is an after-install capability first, then give a pre-install checklist. Boundary: Must be verified after a real install or run. Evidence: `.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` et al. Claim: `clm_0001` supported 0.86 ### Context Scale - Total files: 2017 - Important-file coverage: 40/2017 - Evidence index entries: 80 - Role / Skill entries: 69 ### Handling Insufficient Evidence - **missing_evidence**: State that evidence is insufficient and ask the user for the target file, a README section, or after-install verification records; do not fill in facts. - **out_of_scope_request**: State that the task is beyond the current AI Context Pack's evidence scope and suggest the user check the Human Manual or verify after a real install. - **runtime_request**: Provide a pre-install checklist and command sources, but do not run commands for the user or claim they have been run. - **source_conflict**: Show the conflicting sources side by side, mark them as unverified, and do not force a single version. ## Prompt Recipes ### Fit assessment - Goal: Judge whether this project fits the user's current task. - Expected output: A fit conclusion, key reasons, evidence citations, what can be previewed before install, what must be verified after install, and a next-step recommendation. ```text Based on the AI Context Pack for encore, ask me 3 necessary questions first, then judge whether it fits my task. The answer must cover: who it fits, what it can do, what it cannot do, whether it is worth installing, and where the evidence comes from. Every project fact must cite evidence_refs, source_paths, or a claim_id. ``` ### Pre-install experience - Goal: Let the user feel the core workflow before installing, while avoiding packaging the preview as real capability or a marketing promise. - Expected output: An experience script with boundary labels, an after-install verification checklist, and a cautious recommendation; with no real-run promises or strong marketing language. ```text Treat encore as a pre-install experience asset, not an already-installed tool or a real runtime environment. Output exactly four parts: 1. Ask me 3 necessary questions first. 2. Give an "experience script": use the three labels [Previewable before install], [Must verify after install], and [Insufficient evidence] to show how it might guide the workflow. 3. Give an after-install verification checklist: list which capabilities can only be confirmed after a real install, real host loading, and a real project run. 4. Give a cautious recommendation: only "worth researching/trialing further", "add information before deciding", or "not recommended to continue"; do not endorse the project. Hard boundaries: - Do not claim you have installed, run, executed tests, modified files, or produced real results. - Do not write promise-like phrasing such as "auto-adapts", "guarantees passing", "perfect fit", or "strongly recommend installing". - If you describe how it works after install, you must use a conditional such as "if installed successfully and the host loads the Skill correctly, it might...". - The experience script may only be written as "example lines / hypothetical flow": use "might ask / might suggest / might show", not "has written, has generated, has passed, is running, is generating". - Prompt Preview does not hand out install commands; if the user is ready to trial, only prompt them to read Quick Start and the Risk Card first and to verify in an isolated environment. - Every project fact must come from a supported claim, evidence_refs, or source_paths; inferred/unverified items can only be risks or open questions. ``` ### Role / Skill selection - Goal: Pick the best-matching asset from the project's roles or Skills. - Expected output: A list of candidate roles or Skills, each with an applicable scenario, evidence paths, risk boundary, and whether after-install verification is needed. ```text Read role_skill_index and recommend 3-5 of the most relevant roles or Skills for my target task. For each recommendation, state the applicable scenario, likely output, risk boundary, and evidence_refs. ``` ### Risk pre-check - Goal: Identify environment, permission, rule-conflict, and quality risks before installing or adopting. - Expected output: A checklist of environment, permission, dependency, license, host-conflict, quality risk, and unknown items. ```text Based on risk_card, boundaries, and quick_start_candidates, give me a pre-install risk pre-check list. Do not run commands for me; only explain what I should check, why, and what impact a failure would have. ``` ### Host AI kickoff instruction - Goal: Turn the project context into a host AI instruction for the start of a conversation. - Expected output: A pre-work instruction with clear boundaries and clear evidence citations, suitable to copy to a host AI. ```text Based on the AI Context Pack for encore, generate a pre-work instruction I can paste to my host AI. This instruction must obey not_runtime=true and must not claim the project has been installed, run, or produced real results. ``` ## Role / Skill Index - Indexed 69 role / Skill / project-doc entries. - **What is Encore?** (project_doc): Encore: Infrastructure orchestration from local to your cloud Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `README.md` - **End to End Tests** (project_doc): This folder contains end to end tests for Encore, which test everything in Encore as an end user would use it. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `e2e-tests/README.md` - **Kubernetes Types** (project_doc): This package contains types copied directly from the Kubernetes https://github.com/kubernetes/kubernetes project, this is to prevent the Encore CLI needing to have a dependency on the Kubernetes project for just these types. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `cli/cmd/encore/k8s/types/README.md` - **Readme** (project_doc): ! Build Status https://travis-ci.org/gregjones/httpcache.svg?branch=master https://travis-ci.org/gregjones/httpcache ! GoDoc https://godoc.org/github.com/gregjones/httpcache?status.svg https://godoc.org/github.com/gregjones/httpcache Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `internal/httpcache/README.md` - **pgproxy** (project_doc): pgproxy is a flexible proxy for the Postgres wire protocol that allows for customizing authentication and backend selection by breaking apart the startup message flow between frontend and backend. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `pkg/pgproxy/README.md` - **Encore Runtime** (project_doc): This is the Encore runtime module that provides APIs and internal runtime components for running Encore applications. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `runtimes/go/README.md` - **metrics** (project_doc): This package allows an Encore app to export custom metrics to metric providers. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `runtimes/go/appruntime/infrasdk/metrics/README.md` - **Encore JavaScript/TypeScript SDK** (project_doc): This package contains the Encore JavaScript/TypeScript SDK, it is intended for you to use in your applications to develop against the Encore API. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `runtimes/js/encore.dev/README.md` - **SemGrep Rules** (project_doc): This directory contains a set of Semgrep rules we run against Encore's source code. You can find more information about the syntax of rules in the Semgrep documentation https://semgrep.dev/docs/writing-rules/overview/ . Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `tools/semgrep-rules/README.md` - **Readme** (project_doc): Encore Note We've copied in the rules from https://github.com/dgryski/semgrep-go on 2023-07-27 However delete some rules that we don't want to run in our codebase and updated some other rules. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `tools/semgrep-rules/semgrep-go/README.md` - **txtar** (project_doc): ! crates.io version 1 2 ! docs.rs docs 3 4 ! license 5 6 Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `tsparser/txtar/README.md` - **tsparser-wasm** (project_doc): WebAssembly build of the Encore TypeScript parser. Parses Encore.ts source files in the browser and returns application metadata APIs, services, infrastructure resources, etc. . Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `tsparser/wasm/README.md` - **Install the Encore CLI** (project_doc): If you are new to Encore, we recommend following the quick start guide /docs/go/quick-start . Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/install.md` - **Install the Encore CLI** (project_doc): If you are new to Encore, we recommend following the quick start guide /docs/ts/quick-start . Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/ts/install.md` - **Integration Tests** (project_doc): These are the integration tests from the original miniredis https://github.com/alicebob/miniredis Go implementation integration/ , adapted to compare miniredis-rs against miniredis-go at the RESP byte level. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `miniredis/tests/integration-go/README.md` - **Update Golden Tests** (project_doc): Instead of manually updating the golden tests, once you've verified the output of the tests is correct, then you can simply update all the expected output files files by running Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `pkg/clientgen/testdata/README.md` - **Readme** (project_doc): Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `pkg/vfs/testdata/filteredglob/foosystem/README.md` - **Contributing to Encore** (project_doc): We're so excited that you are interested in contributing to Encore! All contributions are welcome, and there are several valuable ways to contribute. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `CONTRIBUTING.md` - **What AI Enables** (project_doc): Encore is built for AI-assisted development. Encore-specific rules and MCP /docs/go/ai-integration mcp-server integration let AI understand your architecture and generate type-safe code that follows your patterns. Run encore run to start your app; Encore provisions local infrastructure automatically. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/ai-integration.md` - **Running** (project_doc): Flag Description Default --- --- --- -w, --watch Watch for changes and live-reload true --listen Address to listen on e.g. 0.0.0.0:4000 -p, --port Port to listen on 4000 --json Display logs in JSON format false -n, --namespace Namespace to use defaults to active namespace --color Whether to display colorized output auto-detected --redact Redact sensitive data in traces when running locally false -l, --level Minimum… Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/cli/cli-reference.md` - **Generating a Client** (project_doc): Encore makes it simple to write scalable distributed backends by allowing you to make function calls that Encore translates into RPC calls. Encore also generates API clients with interfaces that look like the original Go functions, with the same parameters and response signature as the server. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/cli/client-generation.md` - **Configuration files** (project_doc): The Encore CLI has a number of configuration options to customize its behavior. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/cli/config-reference.md` - **Usage** (project_doc): Encore's CLI allows you to create and switch between multiple, independent infrastructure namespaces . Infrastructure namespaces are isolated from each other, and each namespace contains its own independent data. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/cli/infra-namespaces.md` - **Example: Integrating with Cursor** (project_doc): Encore provides an MCP server that implements the Model Context Protocol https://modelcontextprotocol.io/introduction , an open standard that enables large language models LLMs to access contextual information about your application. Think of MCP as a standardized interface—like a "USB-C port for AI applications"—that connects your Encore app's data and functionality to any LLM that supports the protocol. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/cli/mcp.md` - **Why We Collect Data** (project_doc): Telemetry helps us improve the Encore by collecting usage data. This data provides insights into how Encore is used, enabling us to make informed decisions to enhance performance, add new features, and fix bugs more efficiently. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/cli/telemetry.md` - **Open Source Project** (project_doc): We’re so excited that you are interested in contributing to Encore! All contributions are welcome, and there are several valuable ways to contribute. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/community/contribute.md` - **Get involved** (project_doc): Developers building with Encore are forward-thinkers, who are working on exciting and innovative applications. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/community/get-involved.md` - **License** (project_doc): We believe Open Source is key to a long-term sustainable and prosperous technology community. Encore builds on Open Source software, and is largely Open Source itself. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/community/open-source.md` - **Code of Conduct** (project_doc): Everyone is welcome in the Encore community, and it is of utmost importance to us that everyone is able to feel at home and contribute. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/community/principles.md` - **Submit your contribution** (project_doc): Templates /templates help and inspire developers to build applications using Encore. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/community/submit-template.md` - **Standardization brings clarity** (project_doc): Encore works by using static analysis to understand your application. This is a fancy term for parsing and analyzing the code you write and creating a graph of how your application works. This graph closely represents your own mental model of the system: boxes and arrows that represent systems and services that communicate with other systems, pass data and connect to infrastructure. We call it the Encore Application… Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/concepts/application-model.md` - **No DevOps experience required** (project_doc): Using Encore.go to declare infrastructure in application code helps unlock several benefits: Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/concepts/benefits.md` - **Services** (project_doc): Encore parses doc comments from your Go source code and surfaces them in the Service Catalog /docs/go/observability/service-catalog , generated API clients /docs/go/cli/client-generation , and OpenAPI specs. This means your documentation stays in your code and is always up to date. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/develop/api-docs.md` - **The auth handler** (project_doc): Almost every application needs to know who's calling it, whether the user represents a person in a consumer-facing app or an organization in a B2B app. Encore supports both use cases in a simple yet powerful way. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/develop/auth.md` - **Using Config** (project_doc): Configuration files let you define default behavior for your application, and override it for specific environments. This allows you to make changes without affecting deployments in other environments. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/develop/config.md` - **Configuring CORS** (project_doc): CORS is a web security concept that defines which website origins are allowed to access your API. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/develop/cors.md` - **Daemon & Development Dashboard** (project_doc): Encore works out of the box without configuration, but provides several environment variables for advanced use cases such as debugging, testing, or adapting Encore to specific workflow requirements. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/develop/env-vars.md` - **Application Metadata** (project_doc): While Encore tries to provide a cloud-agnostic environment, sometimes it's helpful to know more about the environment your application is running in. For this reason Encore provides an API for accessing metadata about the application application-metadata and the environment it's running in, as well as information about the current request current-request as part of the encore.dev package. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/develop/metadata.md` - **Middleware functions** (project_doc): Middleware is a way to write reusable code that runs before or after or both the handling of API requests, often across several or all API endpoints. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/develop/middleware.md` - **Mocking Endpoints** (project_doc): Encore comes with built-in support for mocking out APIs and services, which makes it easier to test your application in isolation. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/develop/mocking.md` - **Validation** (project_doc): When receiving incoming requests it's best practice to validate the payload to make sure it meets your expectations, contains all the necessary fields, and so on. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/develop/validation.md` - **About the project** (project_doc): Yes, check out the project on GitHub https://github.com/encoredev/encore . Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/faq.md` - **Setting up GORM** (project_doc): Atlas https://atlasgo.io is a popular tool for managing database migrations. GORM https://gorm.io/ is a popular ORM for Go. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/atlas-gorm.md` - **Communicate with Auth0** (project_doc): In this guide you will learn how to set up an Encore auth handler /docs/go/develop/auth the-auth-handler that makes use of Auth0 https://auth0.com/ in order to add a seamless signup and login experience to your web app. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/auth0-auth.md` - **How to break out a service from a monolith** (project_doc): It's common to want to break out specific functionality into separate services. Perhaps you want to independently scale a specific service, or simply want to structure your codebase in smaller pieces. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/break-up-monolith.md` - **Static linking** (project_doc): Cgo is a feature of the Go compiler that enables Go programs to interface with libraries written in other languages using C bindings. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/cgo.md` - **Set up the auth handler** (project_doc): In this guide you will learn how to set up an Encore auth handler /docs/go/develop/auth the-auth-handler that makes use of Clerk https://clerk.com/ in order to add an integrated signup and login experience to your web app. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/clerk-auth.md` - **Debug by starting the process in debug mode** (project_doc): Encore makes it easy to debug your application using Delve https://github.com/go-delve/delve "Delve" . Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/debug.md` - **Mocking dependencies** (project_doc): Dependency Injection is a fancy name for a simple concept: when you depend on some functionality, add that dependency as a field on your struct and refer to it that way instead of directly calling it. By doing so it becomes easier to test your services by swapping out certain dependencies for other implementations often with the use of interfaces . Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/dependency-injection.md` - **Installation** (project_doc): The Encore Toolbar is a lightweight, drop-in script that adds a floating developer panel to your frontend application. It automatically intercepts all fetch and XMLHttpRequest calls, captures trace IDs from Encore's response headers, and lets you jump directly to the corresponding trace in the Development Dashboard /docs/go/observability/dev-dash or Encore Cloud https://app.encore.dev . Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/encore-toolbar.md` - **Add ent schemas to a service** (project_doc): Encore has all the tools needed to support ORMs and migration frameworks out-of-the-box through named databases /docs/go/primitives/share-db-between-services and migration files /docs/go/primitives/databases defining-a-database-schema . Writing plain SQL might not work for your use case, or you may not want to use SQL in the first place. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/entgo-orm.md` - **Set up auth handler** (project_doc): Encore's authentication support /docs/go/develop/auth provides a simple yet powerful way of dealing with various authentication scenarios. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/firebase-auth.md` - **Define a Connect service** (project_doc): The Connect protocol https://connectrpc.com/ is an HTTP/2-based protocol for RPC communication. It's conceptually similar to gRPC, but with better support for using from browsers and JavaScript clients. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/grpc-connect.md` - **Defining raw endpoints** (project_doc): Encore makes it easy to define APIs and expose them, but it works best when you are in charge of the API schema. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/http-requests.md` - **Logto settings** (project_doc): Logto https://logto.io is a modern Auth0 alternative that helps you build the sign-in experience and user identity within minutes. It's particularly well-suited for protecting API services built with Encore. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/logto-auth.md` - **Publishing messages to the outbox** (project_doc): One of the hardest parts of building an event-driven application is ensuring consistency between services. A common pattern is for each service to have its own database and use Pub/Sub to notify other systems of business events. Inevitably this leads to inconsistencies since the Pub/Sub publishing is not transactional with the database writes. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/pubsub-outbox.md` - **Set up Temporal clusters** (project_doc): Temporal https://temporal.io is a workflow orchestration system for building highly reliable systems. Encore works great with Temporal, and this guide shows you how to integrate Temporal into your Encore application. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/how-to/temporal.md` - **Accommodating for your unique requirements** (project_doc): We realize most people read this page before even trying Encore, so we start with a perspective on how you might reason about adopting Encore. Read on to see what tools are available for migrating away. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/migration/migrate-away.md` - **Dev Dash** (project_doc): Encore provides an efficient local development workflow that automatically provisions local infrastructure /docs/platform/infrastructure/infra local-development and supports automated testing with dedicated test infrastructure. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/observability/dev-dash.md` - **Birds-eye view** (project_doc): Flow is a visual tool that gives you an always up-to-date view of your entire system, helping you reason about your microservices architecture and identify which services depend on each other and how they work together. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/observability/encore-flow.md` - **Usage** (project_doc): Encore offers built-in support for Structured Logging, which combines a free-form log message with structured and type-safe key-value pairs. This enables straightforward analysis of what your application is doing, in a way that is easy for a computer to parse, analyze, and index. This makes it simple to quickly filter and search through logs. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/observability/logging.md` - **Defining custom metrics** (project_doc): Encore provides built-in support for defining custom metrics in your Go applications. Once defined, metrics are automatically collected and displayed in the Encore Cloud Dashboard, and can be exported to third-party observability services. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/observability/metrics.md` - **Service Catalog** (project_doc): All developers agree API documentation is great to have, but the effort of maintaining it inevitably leads to docs becoming stale and out of date. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/observability/service-catalog.md` - **Encore's tracing is more comprehensive and more performant than all other tools** (project_doc): Distributed systems often have many moving parts, making it difficult to understand what your code is doing and finding the root-cause to bugs. That’s where Tracing comes in. If you haven’t seen it before, it may just about change your life. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/observability/tracing.md` - **What you get with Encore.go** (project_doc): Quick Start Guide Try building with Encore.go Get started Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/overview.md` - **Current Request** (project_doc): Calling an API endpoint looks like a regular function call with Encore.go. To call an endpoint you first import the other service as a Go package using import "encore.app/package-name" and then call the API endpoint like a regular function. Encore will automatically generate the necessary boilerplate at compile-time. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/primitives/api-calls.md` - **The errs.Error type** (project_doc): Encore supports returning structured error information from your APIs using the encore.dev/beta/errs https://pkg.go.dev/encore.dev/beta/errs package. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/primitives/api-errors.md` - **Path parameters** (project_doc): APIs in Encore are regular functions with request and response data types. These types are structs or pointers to structs with optional field tags, which Encore uses to encode API requests to HTTP messages. The same struct can be used for requests and responses, but the query tag is ignored when generating responses. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/primitives/api-schemas.md` - **Monolith or Microservices** (project_doc): Encore uses a monorepo design and it's best to use one Encore app for your entire backend application. This lets Encore build an application model that spans your entire app, necessary to get the most value out of many features like distributed tracing /docs/go/observability/tracing and Encore Flow /docs/go/observability/encore-flow . Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/go/primitives/app-structure.md` ## Evidence Index - Indexed 80 evidence entries. - **What is Encore?** (documentation): Encore: Infrastructure orchestration from local to your cloud Evidence: `README.md` - **End to End Tests** (documentation): This folder contains end to end tests for Encore, which test everything in Encore as an end user would use it. Evidence: `e2e-tests/README.md` - **Kubernetes Types** (documentation): This package contains types copied directly from the Kubernetes https://github.com/kubernetes/kubernetes project, this is to prevent the Encore CLI needing to have a dependency on the Kubernetes project for just these types. Evidence: `cli/cmd/encore/k8s/types/README.md` - **Readme** (documentation): ! Build Status https://travis-ci.org/gregjones/httpcache.svg?branch=master https://travis-ci.org/gregjones/httpcache ! GoDoc https://godoc.org/github.com/gregjones/httpcache?status.svg https://godoc.org/github.com/gregjones/httpcache Evidence: `internal/httpcache/README.md` - **pgproxy** (documentation): pgproxy is a flexible proxy for the Postgres wire protocol that allows for customizing authentication and backend selection by breaking apart the startup message flow between frontend and backend. Evidence: `pkg/pgproxy/README.md` - **Encore Runtime** (documentation): This is the Encore runtime module that provides APIs and internal runtime components for running Encore applications. Evidence: `runtimes/go/README.md` - **metrics** (documentation): This package allows an Encore app to export custom metrics to metric providers. Evidence: `runtimes/go/appruntime/infrasdk/metrics/README.md` - **Encore JavaScript/TypeScript SDK** (documentation): This package contains the Encore JavaScript/TypeScript SDK, it is intended for you to use in your applications to develop against the Encore API. Evidence: `runtimes/js/encore.dev/README.md` - **SemGrep Rules** (documentation): This directory contains a set of Semgrep rules we run against Encore's source code. You can find more information about the syntax of rules in the Semgrep documentation https://semgrep.dev/docs/writing-rules/overview/ . Evidence: `tools/semgrep-rules/README.md` - **Readme** (documentation): Encore Note We've copied in the rules from https://github.com/dgryski/semgrep-go on 2023-07-27 However delete some rules that we don't want to run in our codebase and updated some other rules. Evidence: `tools/semgrep-rules/semgrep-go/README.md` - **txtar** (documentation): ! crates.io version 1 2 ! docs.rs docs 3 4 ! license 5 6 Evidence: `tsparser/txtar/README.md` - **tsparser-wasm** (documentation): WebAssembly build of the Encore TypeScript parser. Parses Encore.ts source files in the browser and returns application metadata APIs, services, infrastructure resources, etc. . Evidence: `tsparser/wasm/README.md` - **Install the Encore CLI** (documentation): If you are new to Encore, we recommend following the quick start guide /docs/go/quick-start . Evidence: `docs/go/install.md` - **Install the Encore CLI** (documentation): If you are new to Encore, we recommend following the quick start guide /docs/ts/quick-start . Evidence: `docs/ts/install.md` - **Integration Tests** (documentation): These are the integration tests from the original miniredis https://github.com/alicebob/miniredis Go implementation integration/ , adapted to compare miniredis-rs against miniredis-go at the RESP byte level. Evidence: `miniredis/tests/integration-go/README.md` - **Update Golden Tests** (documentation): Instead of manually updating the golden tests, once you've verified the output of the tests is correct, then you can simply update all the expected output files files by running Evidence: `pkg/clientgen/testdata/README.md` - **Readme** (documentation): This is a example file Evidence: `pkg/vfs/testdata/filteredglob/foosystem/README.md` - **Contributing to Encore** (documentation): We're so excited that you are interested in contributing to Encore! All contributions are welcome, and there are several valuable ways to contribute. Evidence: `CONTRIBUTING.md` - **Package** (package_manifest): { "name": "encore.dev", "description": "Encore's JavaScript/TypeScript SDK", "version": "0.0.0-devel.202311141645", "license": "MPL-2.0", "bugs": { "url": "https://github.com/encoredev/encore/issues" }, "repository": { "type": "git", "url": "https://github.com/encoredev/encore", "directory": "runtimes/js/encore.dev" }, "scripts": { "build": "tsc -b", "lint": "eslint \" / .ts \"", "test": "bun test", "docs": "typedoc && node scripts/postprocess-docs.mjs" }, "type": "module", "sideEffects": false, "exports": { ".": { "types": "./mod.ts", "bun": "./mod.ts", "default": "./dist/mod.js" }, "./api": { "types": "./api/mod.ts", "bun": "./api/mod.ts", "default": "./dist/api/mod.js" }, "./auth": { "ty… Evidence: `runtimes/js/encore.dev/package.json` - **Package** (package_manifest): { "private": true, "type": "module", "scripts": { "test": "node --trace-warnings --experimental-specifier-resolution=node --loader ts-node/esm ./ts/main.ts", "test:js": "node --trace-warnings --experimental-specifier-resolution=node ./js/main.js", "lint": "tsc --noEmit && eslint \" / .{ts,js}\"" }, "devDependencies": { "@types/node": "^17.0.35", "@typescript-eslint/eslint-plugin": "^5.26.0", "@typescript-eslint/parser": "^5.26.0", "eslint": "^8.16.0", "ts-node": "^10.8.0", "typescript": "^4.6.4" }, "dependencies": { "isomorphic-fetch": "^3.0.0" } } Evidence: `e2e-tests/testdata/echo_client/package.json` - **Package** (package_manifest): { "name": "encore-ts-testapp", "private": true, "version": "0.0.1", "description": "Encore Typescript Test app", "license": "MPL-2.0", "type": "module", "scripts": { "test": "vitest" }, "devDependencies": { "@types/node": "^22.5.7", "typescript": "^5.4", "vitest": "^3.1.3" }, "dependencies": { "encore.dev": "file:/Users/andre/src/github.com/encoredev/encore/runtimes/js/encore.dev" }, "optionalDependencies": { "@rollup/rollup-linux-x64-gnu": "^4.13.0" } } Evidence: `e2e-tests/testdata/tsapp/package.json` - **License** (source_file): Mozilla Public License, version 2.0 Evidence: `LICENSE` - **License** (source_file): Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: Evidence: `pkg/editors/LICENSE` - **License** (source_file): Copyright c 2021 Engineering at Fullstory Evidence: `pkg/emulators/storage/LICENSE` - **License** (source_file): Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: Evidence: `pkg/tarstream/LICENSE` - **License** (source_file): Copyright c 2019-2021 Tower Contributors Evidence: `runtimes/core/src/api/cors/cors_headers_config/LICENSE` - **License** (source_file): Copyright c 2013-2021 Jack Christensen Evidence: `runtimes/go/storage/sqldb/internal/stdlibdriver/LICENSE` - **License** (source_file): Mozilla Public License, version 2.0 Evidence: `runtimes/js/encore.dev/LICENSE` - **License** (source_file): Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: Evidence: `tools/semgrep-rules/semgrep-go/LICENSE` - **What AI Enables** (documentation): Encore is built for AI-assisted development. Encore-specific rules and MCP /docs/go/ai-integration mcp-server integration let AI understand your architecture and generate type-safe code that follows your patterns. Run encore run to start your app; Encore provisions local infrastructure automatically. Evidence: `docs/go/ai-integration.md` - **Running** (documentation): Flag Description Default --- --- --- -w, --watch Watch for changes and live-reload true --listen Address to listen on e.g. 0.0.0.0:4000 -p, --port Port to listen on 4000 --json Display logs in JSON format false -n, --namespace Namespace to use defaults to active namespace --color Whether to display colorized output auto-detected --redact Redact sensitive data in traces when running locally false -l, --level Minimum log level to display trace\ debug\ info\ warn\ error --debug Compile for debugging enabled\ break --browser Open local dev dashboard in browser on startup auto\ never\ always auto Evidence: `docs/go/cli/cli-reference.md` - **Generating a Client** (documentation): Encore makes it simple to write scalable distributed backends by allowing you to make function calls that Encore translates into RPC calls. Encore also generates API clients with interfaces that look like the original Go functions, with the same parameters and response signature as the server. Evidence: `docs/go/cli/client-generation.md` - **Configuration files** (documentation): The Encore CLI has a number of configuration options to customize its behavior. Evidence: `docs/go/cli/config-reference.md` - **Usage** (documentation): Encore's CLI allows you to create and switch between multiple, independent infrastructure namespaces . Infrastructure namespaces are isolated from each other, and each namespace contains its own independent data. Evidence: `docs/go/cli/infra-namespaces.md` - **Example: Integrating with Cursor** (documentation): Encore provides an MCP server that implements the Model Context Protocol https://modelcontextprotocol.io/introduction , an open standard that enables large language models LLMs to access contextual information about your application. Think of MCP as a standardized interface—like a "USB-C port for AI applications"—that connects your Encore app's data and functionality to any LLM that supports the protocol. Evidence: `docs/go/cli/mcp.md` - **Why We Collect Data** (documentation): Telemetry helps us improve the Encore by collecting usage data. This data provides insights into how Encore is used, enabling us to make informed decisions to enhance performance, add new features, and fix bugs more efficiently. Evidence: `docs/go/cli/telemetry.md` - **Open Source Project** (documentation): We’re so excited that you are interested in contributing to Encore! All contributions are welcome, and there are several valuable ways to contribute. Evidence: `docs/go/community/contribute.md` - **Get involved** (documentation): Developers building with Encore are forward-thinkers, who are working on exciting and innovative applications. Evidence: `docs/go/community/get-involved.md` - **License** (documentation): We believe Open Source is key to a long-term sustainable and prosperous technology community. Encore builds on Open Source software, and is largely Open Source itself. Evidence: `docs/go/community/open-source.md` - **Code of Conduct** (documentation): Everyone is welcome in the Encore community, and it is of utmost importance to us that everyone is able to feel at home and contribute. Evidence: `docs/go/community/principles.md` - **Submit your contribution** (documentation): Templates /templates help and inspire developers to build applications using Encore. Evidence: `docs/go/community/submit-template.md` - **Standardization brings clarity** (documentation): Encore works by using static analysis to understand your application. This is a fancy term for parsing and analyzing the code you write and creating a graph of how your application works. This graph closely represents your own mental model of the system: boxes and arrows that represent systems and services that communicate with other systems, pass data and connect to infrastructure. We call it the Encore Application Model. Evidence: `docs/go/concepts/application-model.md` - **No DevOps experience required** (documentation): Using Encore.go to declare infrastructure in application code helps unlock several benefits: Evidence: `docs/go/concepts/benefits.md` - **Services** (documentation): Encore parses doc comments from your Go source code and surfaces them in the Service Catalog /docs/go/observability/service-catalog , generated API clients /docs/go/cli/client-generation , and OpenAPI specs. This means your documentation stays in your code and is always up to date. Evidence: `docs/go/develop/api-docs.md` - **The auth handler** (documentation): Almost every application needs to know who's calling it, whether the user represents a person in a consumer-facing app or an organization in a B2B app. Encore supports both use cases in a simple yet powerful way. Evidence: `docs/go/develop/auth.md` - **Using Config** (documentation): Configuration files let you define default behavior for your application, and override it for specific environments. This allows you to make changes without affecting deployments in other environments. Evidence: `docs/go/develop/config.md` - **Configuring CORS** (documentation): CORS is a web security concept that defines which website origins are allowed to access your API. Evidence: `docs/go/develop/cors.md` - **Daemon & Development Dashboard** (documentation): Encore works out of the box without configuration, but provides several environment variables for advanced use cases such as debugging, testing, or adapting Encore to specific workflow requirements. Evidence: `docs/go/develop/env-vars.md` - **Application Metadata** (documentation): While Encore tries to provide a cloud-agnostic environment, sometimes it's helpful to know more about the environment your application is running in. For this reason Encore provides an API for accessing metadata about the application application-metadata and the environment it's running in, as well as information about the current request current-request as part of the encore.dev package. Evidence: `docs/go/develop/metadata.md` - **Middleware functions** (documentation): Middleware is a way to write reusable code that runs before or after or both the handling of API requests, often across several or all API endpoints. Evidence: `docs/go/develop/middleware.md` - **Mocking Endpoints** (documentation): Encore comes with built-in support for mocking out APIs and services, which makes it easier to test your application in isolation. Evidence: `docs/go/develop/mocking.md` - **Validation** (documentation): When receiving incoming requests it's best practice to validate the payload to make sure it meets your expectations, contains all the necessary fields, and so on. Evidence: `docs/go/develop/validation.md` - **About the project** (documentation): Yes, check out the project on GitHub https://github.com/encoredev/encore . Evidence: `docs/go/faq.md` - **Setting up GORM** (documentation): Atlas https://atlasgo.io is a popular tool for managing database migrations. GORM https://gorm.io/ is a popular ORM for Go. Evidence: `docs/go/how-to/atlas-gorm.md` - **Communicate with Auth0** (documentation): In this guide you will learn how to set up an Encore auth handler /docs/go/develop/auth the-auth-handler that makes use of Auth0 https://auth0.com/ in order to add a seamless signup and login experience to your web app. Evidence: `docs/go/how-to/auth0-auth.md` - **How to break out a service from a monolith** (documentation): It's common to want to break out specific functionality into separate services. Perhaps you want to independently scale a specific service, or simply want to structure your codebase in smaller pieces. Evidence: `docs/go/how-to/break-up-monolith.md` - **Static linking** (documentation): Cgo is a feature of the Go compiler that enables Go programs to interface with libraries written in other languages using C bindings. Evidence: `docs/go/how-to/cgo.md` - **Set up the auth handler** (documentation): In this guide you will learn how to set up an Encore auth handler /docs/go/develop/auth the-auth-handler that makes use of Clerk https://clerk.com/ in order to add an integrated signup and login experience to your web app. Evidence: `docs/go/how-to/clerk-auth.md` - **Debug by starting the process in debug mode** (documentation): Encore makes it easy to debug your application using Delve https://github.com/go-delve/delve "Delve" . Evidence: `docs/go/how-to/debug.md` - **Mocking dependencies** (documentation): Dependency Injection is a fancy name for a simple concept: when you depend on some functionality, add that dependency as a field on your struct and refer to it that way instead of directly calling it. By doing so it becomes easier to test your services by swapping out certain dependencies for other implementations often with the use of interfaces . Evidence: `docs/go/how-to/dependency-injection.md` - The remaining 20 evidence entries are in `AI_CONTEXT_PACK.json` or `EVIDENCE_INDEX.json`. ## Rules the Host AI Must Follow - **Treat this asset as pre-work context, not a runtime environment.**: The AI Context Pack contains only an evidence-backed understanding of the project, not the project's executable state. Evidence: `README.md`, `e2e-tests/README.md`, `cli/cmd/encore/k8s/types/README.md` - **When answering the user, distinguish what can be previewed from what can only be verified after install.**: The consumer value of the pre-install experience comes from reducing bad installs and misjudgments, not from pretending to be a real run. Evidence: `README.md`, `e2e-tests/README.md`, `cli/cmd/encore/k8s/types/README.md` ## Questions the User Should Answer First - Which host AI or local environment do you plan to use it in? - Do you just want to experience the workflow first, or are you ready to actually install? - What matters most to you: install cost, output quality, or conflicts with your existing rules? ## Acceptance Checks - Every capability claim can be traced back to a file path in evidence_refs. - AI_CONTEXT_PACK.md does not package previews as a real run. - The user can understand who it fits, what it can do, how to start, and the risk boundaries within 3 minutes. --- ## 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. - **Encore Overview & System Architecture**: importance `high` - source_paths: README.md, cli/cmd/encore/main.go, cli/cmd/encore/root/rootcmd.go, Cargo.toml, go.mod - **SDK Primitives & Resource Declarations**: importance `high` - source_paths: runtimes/go/storage/sqldb/db.go, runtimes/go/pubsub/topic.go, runtimes/go/storage/objects/bucket.go, runtimes/go/storage/cache/cache.go, runtimes/go/cron/cron.go - **Parser & Code Generation Pipeline**: importance `high` - source_paths: v2/parser/parser.go, v2/codegen/gen.go, v2/codegen/apigen/apigen.go, v2/codegen/apigen/maingen/maingen.go, tsparser/src/parser/mod.rs - **Runtime, CLI & Deployment**: importance `high` - source_paths: cli/cmd/encore/run.go, cli/daemon/daemon.go, cli/daemon/run/run.go, cli/daemon/sqldb/manager.go, cli/daemon/dash/dash.go ## Repo Inspection Evidence - repo_clone_verified: true - repo_inspection_verified: true - repo_commit: `3b3cba5099ec9a05839ca3bb4bc1b27fdd27f45d` - inspected_files: `README.md`, `docs/go/ai-integration.md`, `docs/go/cli/cli-reference.md`, `docs/go/cli/client-generation.md`, `docs/go/cli/config-reference.md`, `docs/go/cli/infra-namespaces.md`, `docs/go/cli/mcp.md`, `docs/go/cli/telemetry.md`, `docs/go/community/contribute.md`, `docs/go/community/get-involved.md`, `docs/go/community/open-source.md`, `docs/go/community/principles.md`, `docs/go/community/submit-template.md`, `docs/go/concepts/application-model.md`, `docs/go/concepts/benefits.md`, `docs/go/develop/api-docs.md`, `docs/go/develop/auth.md`, `docs/go/develop/config.md`, `docs/go/develop/cors.md`, `docs/go/develop/env-vars.md` 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: Capability evidence risk requires verification - Trigger: README/documentation is current enough for a first validation pass. - 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: capability.assumptions | https://github.com/encoredev/encore - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 2: Security or permission risk requires verification - Trigger: no_demo - 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: downstream_validation.risk_items | https://github.com/encoredev/encore - 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: no_demo - 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: risks.scoring_risks | https://github.com/encoredev/encore - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 4: Maintenance risk requires verification - Trigger: issue_or_pr_quality=unknown。 - 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: evidence.maintainer_signals | https://github.com/encoredev/encore - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 5: Maintenance risk requires verification - Trigger: release_recency=unknown。 - 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: evidence.maintainer_signals | https://github.com/encoredev/encore - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.