@muskanmeet/invoicing-design-system 0.1.0

package/.local/skills/deployment/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: deployment
+description: Use when the user asks to publish, deploy, or configure deployment settings, deployment geography or regions, or when the user reports their deployed app is broken, asks about production errors, or wants to check server logs.
+---
+
+# Deployment Skill
+
+Configure deployment settings, publish your project, and debug deployment issues.
+
+## When to Use
+
+Use this skill when:
+
+- Configuring how the project should run in production
+- The project is in a working state and ready for publishing
+- The user explicitly asks to publish or deploy the project
+- You've completed implementing a feature and verified it works
+- Setting up deployment for different project types (websites, bots, scheduled jobs)
+- The user reports their deployed application is not working correctly
+- The user wants to see what errors are occurring in production
+- The user needs to debug a runtime issue with their deployed app
+- The user asks to check deployment or server logs
+- The user says their app failed to publish or a deployment build failed
+- After a deployment attempt that the agent initiated fails
+
+## When NOT to Use
+
+- Project has known errors or incomplete features
+- You haven't validated that the project works
+- The user is just testing or prototyping
+
+## Reference Documents
+
+This skill has additional reference documents for specific deployment scenarios. Read them as needed:
+
+- `.local/skills/deployment/references/deployment-logs.md` — How to fetch and analyze runtime deployment logs. Read this when the user's deployed app is misbehaving, the live site is down, or they want to check production logs.
+- `.local/skills/deployment/references/deployment-failure-debugging.md` — How to diagnose and fix deployment build failures. Read this when the user's deployment build fails to publish, the app crashes during the publishing step, or the user asks for help debugging a deployment error.
+
+## Available Functions
+
+### deployConfig(deploymentTarget, run, build, publicDir)
+
+Configure how the project should be deployed to production.
+
+**Parameters:**
+
+- `deploymentTarget` (str, required): "autoscale", "vm", "scheduled", or "static"
+- `run` (list[str], optional): Production run command. First entry is binary/script, rest are arguments
+- `build` (list[str], optional): Build/compile command before deployment
+- `publicDir` (str, required for "static"): Directory containing static files
+
+**Returns:** Dict with `success`, `message`, and configuration details
+
+**Example:**
+
+```javascript
+// Configure a Python web app
+const result = await deployConfig({
+    deploymentTarget: "autoscale",
+    run: ["gunicorn", "--bind=0.0.0.0:5000", "--reuse-port", "main:app"]
+});
+
+// Configure a static site
+const result2 = await deployConfig({
+    deploymentTarget: "static",
+    build: ["npm", "run", "build"],
+    publicDir: "dist"
+});
+
+// Configure an always-running bot
+const result3 = await deployConfig({
+    deploymentTarget: "vm",
+    run: ["python", "bot.py"]
+});
+```
+
+### suggestDeploy()
+
+Prompt the user to click the Publish button after the app is ready. **Only works in the main repl context** — in task-agent/subrepl sessions this callback returns `success: false`. If you are in a task agent, skip this call and instead remind the user to publish from the main version after merging.
+
+### getDeploymentInfo()
+
+Fetch the repl's current deployment metadata directly from the deployments service. Always call this — never guess from memory or environment variables — when you need to know whether the project is published, what its production URL is, or whether the live build is healthy. Do NOT run `echo $REPLIT_DOMAINS` to discover the production URL — inside the dev container that variable holds the `.replit.dev` development domain, not the production URL.
+
+**Returns:** Dict with:
+
+- `success` (bool): `false` when the deployments service is unreachable. Treat as "deployment status unknown" — tell the user the status is currently unavailable rather than asserting there is no deployment
+- `isDeployed` (bool): `true` when an active deployment exists for this repl. When `false`, do not fabricate a URL — there is no production URL to give. If the user wants a production URL or asks what their live URL is, guide them through publishing first via the usual deployment flow (e.g. `suggestDeploy()`).
+- `primaryUrl` (str): fully-qualified production URL with `https://` scheme (a verified custom domain if the user configured one, otherwise the generated `*.replit.app` subdomain). Empty string when not deployed. Use this whenever you need the production URL (e.g. setting a `REPLIT_APP_URL` secret, configuring rewrites in an external CMS, curling the live site, or telling the user where their app is reachable)
+- `additionalUrls` (list[str]): other public URLs (e.g. additional verified custom domains). Empty list when none
+- `deploymentType` (str): one of `"autoscale"`, `"vm"`, `"static"`, `"scheduled"`, or `""` if unknown / not applicable. Matches the `deploymentTarget` vocabulary `deployConfig()` accepts
+- `hasSuccessfulBuild` (bool): `true` only when the deployment's current build is in the `success` status. `false` when the build is still pending, failed, suspended, or no current build exists. When `isDeployed` is `true` but this is `false`, the `primaryUrl` may be unreachable or still be serving a previous successful build — if the user reports the live site is broken, suspect the in-flight or failed build first (see `.local/skills/deployment/references/deployment-failure-debugging.md` for how to investigate)
+- `visibility` (str): publishing visibility of the current build — `"public"` (reachable by anyone on the internet), `"private"` (invited collaborators only), `"password"` (public URL gated by a shared password), or `""` (undeployed, or a deployment kind with no user-facing visibility). Use this to reason about who can actually reach a leaked secret or vulnerable endpoint
+
+**Example:**
+
+```javascript
+const info = await getDeploymentInfo();
+if (!info.success) {
+    console.log("Deployment status unavailable; try again in a moment.");
+} else if (!info.isDeployed) {
+    console.log("This repl has not been published yet.");
+} else {
+    console.log(`Live at ${info.primaryUrl} (${info.deploymentType})`);
+    if (!info.hasSuccessfulBuild) {
+        console.log("Current build is not in the success status — URL may be stale.");
+    }
+}
+```
+
+### fetchDeploymentLogs({ afterTimestamp, beforeTimestamp, message, messageContext })
+
+Fetch and analyze deployment logs. See `.local/skills/deployment/references/deployment-logs.md` for full documentation.
+
+## Deployment Targets
+
+Choose the appropriate deployment target based on your project type:
+
+### autoscale (Recommended Default)
+
+Use for stateless websites and APIs that don't need persistent server memory.
+
+- **Best for:** Web applications, REST APIs, stateless services
+- **Behavior:** Scales up/down based on traffic, only runs when requests arrive
+- **State:** Use databases for persistent state (not server memory)
+- **Cost:** Most cost-effective for variable traffic
+
+```javascript
+await deployConfig({
+    deploymentTarget: "autoscale",
+    run: ["gunicorn", "--bind=0.0.0.0:5000", "app:app"]
+});
+```
+
+### vm (Always Running)
+
+Use for applications that need persistent server-side state or long-running processes.
+
+- **Best for:** Discord/Telegram bots, WebSocket servers, web scrapers, background workers
+- **Behavior:** Always running, maintains state in server memory
+- **State:** Can use in-memory databases, local files, or external databases
+
+```javascript
+await deployConfig({
+    deploymentTarget: "vm",
+    run: ["python", "bot.py"]
+});
+```
+
+### scheduled
+
+Use for cron-like jobs that run on a schedule.
+
+- **Best for:** Data processing, cleanup tasks, periodic reports, batch jobs
+- **Behavior:** Runs on configured schedule, not continuously
+- **Note:** Do NOT use for websites or APIs
+
+```javascript
+await deployConfig({
+    deploymentTarget: "scheduled",
+    run: ["python", "daily_report.py"]
+});
+```
+
+### static
+
+Use for client-side websites with no backend server.
+
+- **Best for:** Static HTML sites, SPAs (React, Vue, etc.), documentation sites
+- **Behavior:** Serves static files directly, no server-side processing
+- **Note:** The `run` command is ignored; must specify `publicDir`
+
+```javascript
+await deployConfig({
+    deploymentTarget: "static",
+    build: ["npm", "run", "build"],
+    publicDir: "dist"
+});
+```
+
+## Run Command Examples
+
+Use production-ready servers, not development servers:
+
+```toml
+# Python with Gunicorn
+run=["gunicorn", "--bind=0.0.0.0:5000", "--reuse-port", "main:app"]
+
+# Python with Streamlit
+run=["streamlit", "run", "main.py"]
+
+# Node.js
+run=["node", "server.js"]
+
+# Multiple processes with bash
+run=["bash", "-c", "gunicorn --reuse-port -w 4 -b 0.0.0.0:8000 app:app & npm run dev"]
+```
+
+## Build Command Examples
+
+Only use build commands when compilation is needed:
+
+```toml
+# TypeScript/bundler
+build=["npm", "run", "build"]
+
+# Multiple build steps
+build=["bash", "-c", "make assets && make compile"]
+
+# Rust
+build=["cargo", "build", "--release"]
+```
+
+## Publishing Geography
+
+Users can choose the geographic region where their app is published. This is configured in the **Advanced** settings of the Publishing tool, not in code. The agent cannot set this programmatically — the user selects it in the Publishing UI before clicking Publish.
+
+Key points:
+
+- **Available on Core, Pro, and Enterprise plans.** Free plan users publish to North America by default.
+- **Geography is permanent.** Once a project is published to a geography, it cannot be changed. Inform the user of this before they publish for the first time.
+- **Compute, database, and Object Storage are colocated** in the selected region automatically.
+- **Enterprise admins can enforce a geography** for all new projects across their organization.
+- **Available regions may change over time.** For the current list of supported geographies, refer the user to the [Publishing Geography docs](https://docs.replit.com/cloud-services/deployments/publishing-geography).
+
+If the user asks about deploying to a specific region (e.g. Europe, Asia, Australia):
+
+- **Not yet published & on Core/Pro/Enterprise:** They can select their preferred geography in the **Advanced** section of the Publishing tool before their first publish.
+- **Not yet published & on the Free plan:** Geography selection is not available — they will publish to North America by default. They can upgrade their plan to choose a region.
+- **Already published:** The geography cannot be changed. Let the user know the selection was locked at first publish.
+- **Enterprise org with enforced geography:** The admin-set geography overrides individual choice. The user publishes to whatever geography their org requires.
+
+Do **not** tell users that Replit only supports US-based infrastructure — multiple geographies are available.
+
+## Best Practices
+
+1. **Validate before publishing**: Always verify the project works before suggesting publish
+2. **Use production servers**: Avoid insecure development servers in production
+3. **Choose the right target**: Match deployment type to your application's needs
+4. **Configure once**: Set up deployment config early, then suggest publishing when ready
+5. **Check workflows first**: Ensure workflows are running without errors before publishing
+
+## Important Notes
+
+1. **User-initiated publishing**: The user must click the Publish button to actually deploy
+2. **Automatic handling**: Publishing handles building, hosting, TLS, and health checks automatically
+3. **Domain**: Published apps are available at a `.replit.app` domain or custom domain if configured
+4. **Production config lives in `.replit`**: Deployment settings (run command, build command, deployment target) are in the `.replit` file's `[deployment]` section.
+
+## Example Workflow
+
+```javascript
+// 1. Configure deployment settings for a web app
+await deployConfig({
+    deploymentTarget: "autoscale",
+    run: ["gunicorn", "--bind=0.0.0.0:5000", "app:app"]
+});
+
+// 2. After verifying the app works, suggest publishing to the user
+await suggestDeploy();
+```

package/.local/skills/deployment/references/deployment-failure-debugging.md

@@ -0,0 +1,243 @@
+# Deployment Failure Debugging Reference
+
+Diagnose and fix deployment build failures by inspecting build history, logs, configuration, and environment.
+
+## When to Read This Reference
+
+Read this when:
+
+- The user says their app failed to publish
+- The user reports their deployed app crashes or shows errors during the publishing step
+- After a deployment attempt that the agent initiated fails
+- The user asks for help debugging a deployment error
+
+Do NOT read this for:
+
+- First-time deployment setup (use the main deployment skill instructions above)
+- Checking runtime logs for a working production deployment (use `references/deployment-logs.md`)
+- Issues about development-mode behavior, not production
+
+## Available Functions
+
+### listDeploymentBuilds(limit?)
+
+List recent deployment builds for the current repl.
+
+**Parameters:**
+
+- `limit` (int, optional): Max builds to return (1-100, default 10)
+
+**Returns:** `{ success, builds }` where each build has:
+
+- `id` — build UUID
+- `status` — e.g. `"success"`, `"failed"`, `"building"`
+- `provider` — e.g. `"autoscale"`, `"vm"`
+- `timeCreated` — ISO timestamp
+- `timeUpdated` — ISO timestamp (may be absent)
+- `user` — `{ id, username, displayName }` (may be absent)
+
+**Example:**
+
+```javascript
+const result = await listDeploymentBuilds({ limit: 5 });
+if (result.success) {
+    console.log(JSON.stringify(result.builds, null, 2));
+}
+```
+
+### getDeploymentBuild(buildId, skipLogs?)
+
+Get detailed information about a specific deployment build, including build logs.
+
+**Parameters:**
+
+- `buildId` (string, required): The build ID to inspect
+- `skipLogs` (bool, optional): If true, omit build log lines (default false)
+
+**Returns:** `{ success, build }` where build has:
+
+- `id`, `status`, `provider`, `timeCreated`, `timeUpdated` — same as list summary
+- `suspendedReason` — reason if deployment was suspended (may be absent)
+- `user` — `{ id, username, displayName }` (may be absent)
+- `machineConfiguration` — `{ slug, vcpu, memory }` (may be absent)
+- `logs` — array of build log line strings (may contain ANSI escape codes)
+
+**Example:**
+
+```javascript
+const result = await getDeploymentBuild({ buildId: "b222be9b-63d4-405a-a6ba-11948a8a0df1" });
+if (result.success) {
+    console.log("Status:", result.build.status);
+    const logs = result.build.logs || [];
+    console.log(`Total log lines: ${logs.length}`);
+    // Print only the last 80 lines — build errors are near the end
+    // and full logs may exceed the 4K stdout observation limit.
+    const tail = logs.slice(-80);
+    for (const line of tail) {
+        console.log(line);
+    }
+}
+```
+
+### Related functions from other skills
+
+These existing callbacks are useful during debugging:
+
+- `fetchDeploymentLogs({ afterTimestamp?, beforeTimestamp?, message? })` — fetch runtime/production logs (see `references/deployment-logs.md`). Use to check what happens after the app starts in production.
+- `viewEnvVars({ environment: "development" | "production" })` — compare env var names between dev and prod (from `environment-secrets` skill). Use to find missing production secrets.
+- `deployConfig({ deploymentTarget, run?, build?, publicDir? })` — reconfigure deployment settings (from the main deployment skill). Use to fix run commands and build commands.
+- `suggestDeploy()` — prompt the user to click Publish after making fixes. **Only works in the main repl context** — in task-agent/subrepl sessions this callback returns `success: false`. If you are in a task agent, skip this call and instead remind the user to publish from the main version after merging.
+
+## Diagnostic Procedure
+
+Follow these steps systematically. Do not skip ahead.
+
+### Step 1: Get the build history
+
+```javascript
+const result = await listDeploymentBuilds({ limit: 5 });
+if (!result.success) {
+    console.log("Error fetching builds:", result.error);
+} else {
+    console.log(JSON.stringify(result.builds, null, 2));
+}
+```
+
+If the callback fails (e.g. no deployment configured, transient error), report the error to the user before proceeding.
+
+Identify the most recent failed build. If all recent builds succeeded, the issue may be a runtime problem rather than a build failure — check runtime logs with `fetchDeploymentLogs()` instead.
+
+### Step 2: Get the failed build details
+
+```javascript
+const detail = await getDeploymentBuild({ buildId: "<failed-build-id>" });
+if (!detail.success) {
+    console.log("Error fetching build details:", detail.error);
+} else {
+    console.log("Status:", detail.build.status);
+    const logs = detail.build.logs || [];
+    console.log(`Total log lines: ${logs.length}`);
+    // Only print the last 80 lines — errors appear near the end
+    // and full logs may exceed the 4K stdout observation limit.
+    const tail = logs.slice(-80);
+    for (const line of tail) {
+        console.log(line);
+    }
+}
+```
+
+If the callback fails (e.g. stale build ID, transient error), report the error and retry or fall back to runtime logs.
+
+Read the build logs carefully. The failure cause is almost always near the end of the log output. If the tail doesn't contain enough context, fetch an earlier window with `logs.slice(-160, -80)`.
+
+A deployment goes through these phases in order: **build** → **promote** → **serve**. The build logs show which phase failed:
+
+- **Build phase failures** look like compilation errors, `npm install` failures, missing dependencies, or build commands exiting non-zero.
+- **Promote phase failures** look like the build succeeding (e.g. image pushed, container started) followed by the container failing to become ready. What "ready" means depends on the deployment target:
+  - **`autoscale` and HTTP-serving `vm`**: the deployer sends a startup probe and waits for an HTTP 200 response. Build logs mention health checks, startup probes, or readiness probes timing out. The default probe path is `GET /`. The probe fails if the app crash-loops, returns non-200 on the probe path, binds to the wrong host/port, or takes too long to start.
+  - **non-HTTP `vm` (Discord bots, workers, etc.) and `scheduled` jobs**: there is no HTTP probe. The promote step fails when the run command exits non-zero or crashes during startup. Build logs typically just show the process exiting with a stack trace or non-zero exit code. Do **not** look for an HTTP route in this case — the failure is the process itself.
+  - **`static`**: there is no run command, so promote-step failures here are rare and usually mean `publicDir` is empty or misconfigured.
+- **Serve phase failures** happen after a successful promote: the app is live but throws errors at runtime. These show up in `fetchDeploymentLogs()`, not in build logs.
+
+### Step 3: Branch on what you find
+
+**Build logs show a clear error in the build phase** (compilation error, missing dependency, command not found):
+→ Fix the code or configuration directly. See Common Failure Modes below.
+
+**Build phase succeeded but the promote step failed** (build logs mention health check, startup probe, container failing to start, the process exiting, or the deployment never became ready):
+→ First check the deployment target in `.replit`'s `[deployment]` section — the right diagnosis depends on it.
+→ For **`autoscale` and HTTP-serving `vm`**: the app is failing the startup probe. The default probe is `GET /`. The probe can fail because the app crash-loops on startup, the probe path returns non-200, or the app binds to the wrong host/port. See "Health check / promote step failure" and "Application crashes on startup" below.
+→ For **non-HTTP `vm` (bots, workers) and `scheduled` jobs**: the run command exited non-zero or crashed before becoming healthy. There is no HTTP probe — do not chase a `/` route. See "Application crashes on startup" below.
+→ Either way, check runtime logs to see why the process is failing: `fetchDeploymentLogs({ message: "(?i)(error|exception|failed|crash|traceback)" })`.
+
+**No obvious cause from build logs:**
+→ Check runtime logs for post-deploy errors.
+→ Check environment variables: compare `viewEnvVars({ environment: "development" })` with `viewEnvVars({ environment: "production" })`.
+
+**Build status is `suspended`:**
+→ Check `suspendedReason`. This is usually a billing or quota issue, not a code problem. Inform the user.
+
+### Step 4: Check deployment configuration
+
+Read `.replit`'s `[deployment]` section. Verify run command, build command, and deployment target are correct. Use `deployConfig()` to fix any misconfigured settings.
+
+### Step 5: After fixing
+
+After making code or configuration fixes:
+
+- **Main repl context:** Call `suggestDeploy()` to prompt the user to re-publish.
+- **Task-agent / subrepl context:** Do **not** call `suggestDeploy()` — it will fail. Instead, remind the user to publish from the main version of the project after the task branch is merged.
+
+## Common Failure Modes
+
+### Application crashes on startup
+
+- **Indicators:** Build succeeds, but the deployment fails at the **promote step**. How this surfaces depends on the deployment target:
+  - **`autoscale` / HTTP-serving `vm`**: build logs mention the container failing health checks, the startup probe timing out, or the deployment never becoming ready. A crashing or crash-looping app cannot respond to the probe, so the promote step fails.
+  - **non-HTTP `vm` (bots, workers) / `scheduled` jobs**: build logs show the run command exiting with a stack trace or non-zero exit code, or the process restarting repeatedly. There is no HTTP probe — the failure is just the process dying.
+- **Look for:** Uncaught exceptions, import errors, missing modules, missing environment variables (e.g. `DISCORD_TOKEN`), syntax errors, or repeated restarts in runtime logs (`fetchDeploymentLogs`).
+- **Fix:** Read the stack trace and fix the code error so the app starts cleanly and stays up. Confirm by running the production `run` command locally:
+  - For HTTP services: it must start without crashing **and** respond 200 on the probe path (`GET /` by default).
+  - For bots/workers/jobs: it must start without crashing and stay running (or, for `scheduled`, run to completion with exit code 0). If the crash is from a missing secret, use `requestEnvVar()` to ask the user to add it to production.
+
+### Build command failure
+
+- **Indicators:** Build status `failed`, build logs show non-zero exit from build command.
+- **Look for:** TypeScript compilation errors, missing dependencies not in package.json/requirements.txt, build scripts that reference dev-only paths.
+- **Fix:** Ensure the build command succeeds locally before deploying. Check that all dependencies are listed in the manifest.
+
+### Run command failure or misconfiguration
+
+- **Indicators:** Build logs show command not found or immediate exit.
+- **Common causes:** Run command references a file that doesn't exist, uses a dev server instead of production server, wrong binary name.
+- **Fix:** Verify the run command in `.replit` `[deployment]` section. Use production servers: `gunicorn` not `flask run`, `node server.js` not `npm run dev`.
+
+### Port/binding issues
+
+- **Indicators:** Build succeeds, but app fails health check or port check.
+- **Common causes:**
+  - App binds to `localhost`/`127.0.0.1` instead of `0.0.0.0` — the container can't reach it.
+  - App binds to a different port than configured.
+  - App uses a `PORT` env var that isn't set in production.
+- **Fix:** Ensure the app binds to `0.0.0.0` on the correct port.
+
+### Health check / promote step failure
+
+- **Indicators:** The **build phase succeeds** but the deployment fails at the **promote step**. Build logs mention health check failures, startup probe timeouts, the container failing to become ready, or the deployment never reaching the live state. This is one of the most common deployment failure modes and it is **not** a build problem — the artifact built fine, the app just isn't responding to the probe.
+- **Details:** Before promoting a deployment to live, the deployer sends a startup probe to `GET /` and requires an HTTP 200 response. If the probe doesn't get a 200 within the timeout, the promote step fails and the previous version (if any) keeps serving traffic.
+- **Common causes:**
+  - **App crashes or crash-loops on startup** — a crashing app obviously can't respond to the probe. Check runtime logs for stack traces. See "Application crashes on startup" above.
+  - App returns 404, 3xx redirect, or 5xx on `/`.
+  - App requires authentication on all routes including `/`.
+  - App binds to `localhost`/`127.0.0.1` instead of `0.0.0.0`, or to the wrong port.
+  - App takes too long to start (slow imports, blocking startup work, large model downloads).
+- **Fix:** Ensure the root route `/` returns a 200 response. Use `fetchDeploymentLogs()` to see whether the app is crashing or just responding incorrectly. Optimize startup time if needed.
+
+### Missing or different environment variables
+
+- **Indicators:** App works in dev but fails in prod with connection errors, auth failures, or undefined config.
+- **Fix:** Use `viewEnvVars({ environment: "development" })` and `viewEnvVars({ environment: "production" })` to compare. Use `requestEnvVar()` to ask the user to provide missing production secrets.
+
+### Autoscale-specific issues (stateless footguns)
+
+Autoscale deployments are **stateless Cloud Run services**. Each request may hit a different instance. Instances spin down when idle.
+
+**Things that will NOT work on autoscale:**
+
+- In-memory state (sessions, caches, counters) — use a database or Redis instead
+- SQLite — filesystem is ephemeral, use PostgreSQL
+- WebSocket connections that need to persist — instances can be killed at any time
+- Background workers / long-running processes — these get killed when the request ends
+- Cron jobs or scheduled tasks running inside the app — use the `scheduled` deployment type
+- File uploads stored on the local filesystem — use object storage
+
+
+If the app needs any of the above, inform the user that they should switch to Reserved VM (`vm`) deployment type in the Deployments pane. The deployment type is not something you can change programmatically — the user must change it themselves.
+
+## Important Notes
+
+1. **Don't diagnose infrastructure problems.** If the error appears to be on Replit's side (e.g., transient cloud provider issues, `UnknownError` from the deployer), suggest the user retry the deployment or contact Replit support.
+2. **Changing deployment type.** The deployment type (autoscale, vm, scheduled, static) is set in the Deployments pane, not in code. If it needs to change, tell the user to update it themselves.
+3. **Use production terminology.** In user-facing messages, say "publish" not "deploy" — that's the Replit product terminology.
+4. **You cannot trigger a deployment.** In the main repl, call `suggestDeploy()` to prompt the user to click the Publish button. In task-agent/subrepl sessions, `suggestDeploy()` is unavailable — remind the user to publish from the main version after merging.
+5. **Production config lives in `.replit`.** Deployment settings (run command, build command, deployment target) are in the `.replit` file's `[deployment]` section.

package/.local/skills/deployment/references/deployment-logs.md

@@ -0,0 +1,147 @@
+# Deployment Logs Reference
+
+Fetch and analyze deployment logs to debug runtime issues and monitor your deployed application.
+
+## When to Read This Reference
+
+Read this when:
+
+- The user reports that their deployed application is not working correctly
+- The user wants to see what errors are occurring in production
+- The user needs to debug a runtime issue after deployment
+- The user asks to check deployment or server logs
+- The user wants to monitor application behavior after deployment
+
+## How to Use
+
+In the JavaScript notebook, call the `fetchDeploymentLogs` function:
+
+```javascript
+const result = await fetchDeploymentLogs({
+    afterTimestamp: (Date.now() - 3600 * 1000),  // Last hour
+    message: "ERROR"
+});
+if (result.found) {
+    console.log(result.logs);
+} else {
+    console.log("No deployment logs found.");
+}
+```
+
+## Parameters
+
+- `afterTimestamp` (float, optional): Only include logs after this Unix timestamp (milliseconds)
+- `beforeTimestamp` (float, optional): Only include logs before this Unix timestamp (milliseconds)
+- `message` (str, optional): RE2 regular expression to filter logs by message content
+- `messageContext` (dict, optional): Context configuration for regex matches with:
+  - `lines` (int, required): Number of lines before/after each match (0-100)
+  - `limit` (int, required): Max matches to fetch context for (1-10)
+
+## Return Value
+
+Returns a dictionary with:
+
+- `logs`: String containing the formatted deployment logs (empty string if none found)
+- `found`: Boolean indicating whether any logs were found
+- `message`: Optional message when no logs are found
+
+## Best Practices
+
+1. **Start broad, then filter**: First fetch logs without filters to understand what's available, then use `message` regex to narrow down
+2. **Use timestamps for recent issues**: If the user reports a recent issue, use `afterTimestamp` to focus on recent logs
+3. **Filter by log level**: Use message regex like `"ERROR"` or `"WARN"` to find problematic entries
+4. **Look for patterns**: Search for specific error messages, stack traces, or module names
+5. **Use context for debugging**: When investigating specific errors, use `messageContext` to see surrounding log lines (similar to `rg -C`)
+
+## Examples
+
+### Fetch All Recent Logs
+
+```javascript
+const result = await fetchDeploymentLogs();
+console.log(result.logs);
+```
+
+### Fetch Logs from Last Hour
+
+```javascript
+const oneHourAgo = Date.now() - 3600 * 1000;  // Convert to milliseconds
+const result = await fetchDeploymentLogs({ afterTimestamp: oneHourAgo });
+if (result.found) {
+    console.log(result.logs);
+}
+```
+
+### Find Error Logs
+
+```javascript
+const result = await fetchDeploymentLogs({ message: "ERROR" });
+if (result.found) {
+    console.log(result.logs);
+} else {
+    console.log("No error logs found");
+}
+```
+
+### Find Database-Related Errors
+
+```javascript
+const result = await fetchDeploymentLogs({
+    message: "(?i)(database|postgres|mysql|mongo|connection.*refused)"
+});
+console.log(result.logs);
+```
+
+### Find Startup Failures
+
+```javascript
+const result = await fetchDeploymentLogs({
+    message: "(?i)(failed|crash|exception|traceback)"
+});
+console.log(result.logs);
+```
+
+### Find Errors with Context Lines
+
+```javascript
+// Get 10 lines of context before/after each error (up to 3 matches)
+const result = await fetchDeploymentLogs({
+    message: "ERROR",
+    messageContext: { lines: 10, limit: 3 }
+});
+if (result.found) {
+    console.log(result.logs);
+}
+```
+
+### Combined Time and Pattern Filter
+
+```javascript
+// Get logs from the last 30 minutes containing errors
+const thirtyMinAgo = Date.now() - 1800 * 1000;
+const result = await fetchDeploymentLogs({
+    afterTimestamp: thirtyMinAgo,
+    message: "(?i)(error|exception|failed)"
+});
+if (result.found) {
+    console.log(result.logs);
+} else {
+    console.log("No matching logs in the last 30 minutes");
+}
+```
+
+## Common Log Patterns to Search For
+
+- **Any errors**: `"ERROR"`
+- **Warnings and errors**: `"(WARN|ERROR)"`
+- **Database issues**: `"(?i)database|postgres|mysql|connection"`
+- **Network errors**: `"(?i)timeout|refused|unreachable"`
+- **Authentication**: `"(?i)auth|token|unauthorized|forbidden"`
+- **Memory issues**: `"(?i)memory|heap|oom|killed"`
+- **Import/module errors**: `"(?i)import|module|cannot find"`
+
+## Troubleshooting Tips
+
+1. **No logs returned**: The deployment may not have run recently, or there may be no logs matching your filter
+2. **Too many logs**: Use the `message` parameter to filter, or narrow the time range
+3. **Looking for specific errors**: Use case-insensitive regex with `(?i)` prefix

package/.local/skills/design/.fingerprint

@@ -0,0 +1 @@
+c192a78afc9045b95e270929e4614e99