docs: clarify instrument.cjs is created in the user's own app

[sagnik11]

The getting-started flow has readers clone this repo in step 2 to run the ingester locally, then step 3 says "Create instrument.cjs" without saying where. A reader who just cloned autter-runtime can reasonably assume the file belongs in the clone.

Both docs/GETTING-STARTED.md and the README backend quickstart now state the file is created in your own application's repository, next to the entry point of the service being instrumented, with one file per service in a monorepo.

The hosted docs (autter.dev/docs Runtime tab) get the same wording in a companion PR.

---

Created with PostHog Desktop

---

Summary

Summary generated by Autter.
Clarifies that instrument.cjs is created in the user's application repository, not in the cloned autter-runtime repository. The README and getting-started guide now explicitly distinguish the ingester checkout from the app being instrumented.

Changes

• Updated docs/GETTING-STARTED.md to explain that instrument.cjs belongs next to the instrumented application's entry point.
• Updated README.md to describe instrument.cjs as a file created in the user's own app.
• No runtime code, package APIs, or deployment configuration were changed; there are no breaking changes.

Acceptance Criteria

Documentation clearly states where users should create instrument.cjs and distinguishes their application repository from the autter-runtime checkout.

Test Plan

• Review the updated README instructions and confirm they identify the user's application repository as the location for instrument.cjs.
• Review the getting-started guide and confirm the repository distinction is clear in both the setup and backend instrumentation steps.
• Follow the documented commands against a sample application to verify the instructions remain internally consistent.

Rollback Plan

Documentation-only change; revert the commits touching README.md and docs/GETTING-STARTED.md if needed.

Related Issues

No linked issue was identified.

^{Written for commit 91713cd. Summary will update on new commits.}

[autter-dev]

🔴 Autter review in progress — running security, correctness & dependency checks on this PR. Follow live step-by-step progress on the autter/review-gate check in the merge box. Merge is blocked until the gate completes; Autter approves automatically when the review comes back clean, and releases this hold with a neutral review when it finds non-blocking issues.

[autter-dev]

🚦 Pre-merge checks · ⚠️ 2 warning, ✅ 160 passed

Needs attention

Check	Status	Explanation
Missing linked tracker issue	⚠️ Warning	2 potential issue(s) detected (max risk 50/100): docs/GETTING-STARTED.md:93, README.md:57.
Missing CODEOWNERS reviewer approval	⚠️ Warning	2 potential issue(s) detected (max risk 45/100): README.md:57, docs/GETTING-STARTED.md:93.

✅ Passed checks (160)

Check	Status	Explanation
Too many files changed	✅ Passed	Changed 2 file(s), within the limit of 50.
Too many lines changed	✅ Passed	Changed 9 line(s), within the limit of 1000.
Too many unrelated chapters	✅ Passed	1 chapter(s) detected, within the limit of 6.
Generated files hiding real changes	✅ Passed	Generated-file volume (0 lines) does not obscure the 9 hand-written line(s).
Missing PR context	✅ Passed	PR context looks sufficient.
Mixed concerns (refactor + behavior change)	✅ Passed	Documentation-only clarification; no refactor is combined with a behavior change.
Migration + app logic + UI combined in one PR	✅ Passed	No database migrations, application logic changes, or UI changes are included.
Sensitive data in logs	✅ Passed	No sensitive data in logs issues detected.
Log injection	✅ Passed	No log injection issues detected.
Missing audit logging	✅ Passed	No missing audit logging issues detected.
Removed observability	✅ Passed	No removed observability issues detected.
Silent exception swallowing	✅ Passed	No silent exception swallowing issues detected.
Unhandled promise rejection	✅ Passed	No unhandled promise rejection issues detected.
Circuit breaker not detected	✅ Passed	No circuit breaker not detected issues detected.
Stack trace leakage	✅ Passed	No stack trace leakage issues detected.
Multi-write without detected transaction	✅ Passed	No multi-write without detected transaction issues detected.
Possible TOCTOU in critical path	✅ Passed	No possible toctou in critical path issues detected.
Idempotency key not detected	✅ Passed	No idempotency key not detected issues detected.
Possible non-atomic read-modify-write	✅ Passed	No possible non-atomic read-modify-write issues detected.
Optimistic locking not detected	✅ Passed	No optimistic locking not detected issues detected.
Rate limiting not detected	✅ Passed	No rate limiting not detected issues detected.
Rate limiting removed	✅ Passed	No rate limiting removed issues detected.
Batch size limit not detected	✅ Passed	No batch size limit not detected issues detected.
Pagination not detected	✅ Passed	No pagination not detected issues detected.
Publicly exposed storage	✅ Passed	No publicly exposed storage issues detected.
Over-permissive IAM policy	✅ Passed	No over-permissive iam policy issues detected.
Security group open to the internet	✅ Passed	No security group open to the internet issues detected.
Unencrypted storage at rest	✅ Passed	No unencrypted storage at rest issues detected.
Infrastructure missing access logging	✅ Passed	No infrastructure missing access logging issues detected.
Hardcoded secret in IaC	✅ Passed	No hardcoded secret in iac issues detected.
Infrastructure misconfiguration	✅ Passed	No infrastructure misconfiguration issues detected.
Deprecated Kubernetes API version	✅ Passed	No deprecated kubernetes api version issues detected.
Compound IaC attack chain	✅ Passed	No compound iac attack chain issues detected.
Prompt injection risk	✅ Passed	No LLM/AI-integration code touched by this diff.
LLM output used in a dangerous sink	✅ Passed	No LLM/AI-integration code touched by this diff.
Sensitive data in prompt or system-prompt leakage	✅ Passed	No LLM/AI-integration code touched by this diff.
Over-privileged LLM tool / excessive agency	✅ Passed	No LLM/AI-integration code touched by this diff.
Missing validation on an LLM-driven decision	✅ Passed	No LLM/AI-integration code touched by this diff.
Unbounded LLM usage (denial-of-wallet)	✅ Passed	No LLM/AI-integration code touched by this diff.
Table exposed without row-level security	✅ Passed	No row-level-security-related code touched by this diff.
Over-broad row-level security policy	✅ Passed	No row-level-security-related code touched by this diff.
Code path that bypasses row-level security	✅ Passed	No row-level-security-related code touched by this diff.
Privileged database credential reachable from the client	✅ Passed	No row-level-security-related code touched by this diff.
Privileged query without row-level scoping	✅ Passed	No row-level-security-related code touched by this diff.
Template-default gradient styling	✅ Passed	No added frontend pages or design-slop markers in this diff.
Interchangeable AI marketing copy	✅ Passed	No added frontend pages or design-slop markers in this diff.
Placeholder content shipped to users	✅ Passed	No added frontend pages or design-slop markers in this diff.
Emoji standing in for an icon system	✅ Passed	No added frontend pages or design-slop markers in this diff.
Call-to-action that goes nowhere	✅ Passed	No added frontend pages or design-slop markers in this diff.
Templated page composition	✅ Passed	No added frontend pages or design-slop markers in this diff.
Merge-blocking marker left in the change	✅ Passed	No pending-work markers added by this diff.
Known-defect marker shipped in code	✅ Passed	No pending-work markers added by this diff.
Untracked TODO without an issue reference	✅ Passed	No pending-work markers added by this diff.
Test disabled or left pending	✅ Passed	No pending-work markers added by this diff.
PII in logs	✅ Passed	No pii in logs issues detected.
PII or internals leaked in error response	✅ Passed	No pii or internals leaked in error response issues detected.
PII stored without application-level encryption	✅ Passed	No pii stored without application-level encryption issues detected.
User data stored without retention controls	✅ Passed	No user data stored without retention controls issues detected.
PII sent to external / cross-border destination	✅ Passed	No pii sent to external / cross-border destination issues detected.
Lockfile resolution / integrity tampered	✅ Passed	No lockfile resolution / integrity tampered issues detected.
Dependency runs install-time lifecycle script	✅ Passed	No dependency runs install-time lifecycle script issues detected.
Possible dependency-confusion attack	✅ Passed	No possible dependency-confusion attack issues detected.
Lockfile resolves a dependency the manifest does not declare	✅ Passed	No lockfile resolves a dependency the manifest does not declare issues detected.
Checked-in build artefact modified without source change	✅ Passed	No checked-in build artefact modified without source change issues detected.
Dockerfile build-step is insecure	✅ Passed	No dockerfile build-step is insecure issues detected.
External artefact pulled in without integrity pinning	✅ Passed	No external artefact pulled in without integrity pinning issues detected.
Changed export, importer not updated	✅ Passed	No changed export with an un-updated importer detected.
Missing security-team review on sensitive path	✅ Passed	No missing security-team review on sensitive path issues detected.
Source changes without matching tests	✅ Passed	No source changes without matching tests issues detected.
Migration missing rollback / down step	✅ Passed	No migration missing rollback / down step issues detected.
Frontend importing database client directly	✅ Passed	No frontend importing database client directly issues detected.
Route handler bypassing service layer	✅ Passed	No route handler bypassing service layer issues detected.
Backend service importing UI module	✅ Passed	No backend service importing ui module issues detected.
Cross-context internals import	✅ Passed	No cross-context internals import issues detected.
Workspace package rule violation	✅ Passed	No workspace package rule violation issues detected.
Inconsistent logging pattern	✅ Passed	No inconsistent logging pattern issues detected.
Inconsistent error handling	✅ Passed	No inconsistent error handling issues detected.
Endpoint missing input validation	✅ Passed	No endpoint missing input validation issues detected.
Multi-write without transaction wrapper	✅ Passed	No multi-write without transaction wrapper issues detected.
New feature shipped without feature flag	✅ Passed	No new feature shipped without feature flag issues detected.
Module placed in the wrong workspace package	✅ Passed	No module placed in the wrong workspace package issues detected.
Direct env-var access bypasses config module	✅ Passed	No direct env-var access bypasses config module issues detected.
Hallucinated import (package not installed)	✅ Passed	No hallucinated import (package not installed) issues detected.
Nonexistent package (not found in registry)	✅ Passed	No nonexistent package (not found in registry) issues detected.
Call to function that does not exist	✅ Passed	No call to function that does not exist issues detected.
Generic placeholder identifier in production logic	✅ Passed	No generic placeholder identifier in production logic issues detected.
Repetitive boilerplate (duplicated block)	✅ Passed	No repetitive boilerplate (duplicated block) issues detected.
Overbroad try/catch swallowing all exceptions	✅ Passed	No overbroad try/catch swallowing all exceptions issues detected.
TODO / FIXME on critical path	✅ Passed	No todo / fixme on critical path issues detected.
Comment contradicts or fabricates code behaviour	✅ Passed	No comment contradicts or fabricates code behaviour issues detected.
Abstraction defined but never used	✅ Passed	No abstraction defined but never used issues detected.
Code style differs from rest of codebase	✅ Passed	No code style differs from rest of codebase issues detected.
Established pattern ignored	✅ Passed	No established pattern ignored issues detected.
Unhandled edge case (null / empty / zero / boundary)	✅ Passed	No unhandled edge case (null / empty / zero / boundary) issues detected.
Doc-copy code with insecure defaults	✅ Passed	No doc-copy code with insecure defaults issues detected.
Dead code (defined but never referenced)	✅ Passed	No dead code (defined but never referenced) issues detected.
Deprecated API call	✅ Passed	No deprecated api call issues detected.
API pattern from wrong library version	✅ Passed	No api pattern from wrong library version issues detected.
API endpoint removed	✅ Passed	No api endpoint removed issues detected.
HTTP method changed (GET ↔ POST etc.)	✅ Passed	No http method changed (get ↔ post etc.) issues detected.
New required field added to request	✅ Passed	No new required field added to request issues detected.
Field removed from response schema	✅ Passed	No field removed from response schema issues detected.
Response field type changed	✅ Passed	No response field type changed issues detected.
HTTP status code changed	✅ Passed	No http status code changed issues detected.
Auth requirement added / removed / changed	✅ Passed	No auth requirement added / removed / changed issues detected.
Error response shape changed	✅ Passed	No error response shape changed issues detected.
Pagination behaviour changed	✅ Passed	No pagination behaviour changed issues detected.
Outbound webhook payload schema changed	✅ Passed	No outbound webhook payload schema changed issues detected.
GraphQL field removed without deprecation	✅ Passed	No graphql field removed without deprecation issues detected.
GraphQL enum value removed	✅ Passed	No graphql enum value removed issues detected.
SQL injection	✅ Passed	No sql injection issues detected.
Cross-site scripting (XSS)	✅ Passed	No cross-site scripting (xss) issues detected.
Path traversal	✅ Passed	No path traversal issues detected.
Command injection	✅ Passed	No command injection issues detected.
Insecure deserialization	✅ Passed	No insecure deserialization issues detected.
Weak cryptography	✅ Passed	No weak cryptography issues detected.
Hardcoded secret	✅ Passed	No hardcoded secret issues detected.
Insecure randomness for security material	✅ Passed	No insecure randomness for security material issues detected.
Unsafe file upload	✅ Passed	No unsafe file upload issues detected.
Missing input validation	✅ Passed	No missing input validation issues detected.
Unsafe CORS configuration	✅ Passed	No unsafe cors configuration issues detected.
Unsafe / open redirect	✅ Passed	No unsafe / open redirect issues detected.
Missing CSRF protection	✅ Passed	No missing csrf protection issues detected.
Unsafe cookie / session settings	✅ Passed	No unsafe cookie / session settings issues detected.
Sensitive data exposure	✅ Passed	No sensitive data exposure issues detected.
API key in source	✅ Passed	No api key in source detected.
Access token in source	✅ Passed	No access token in source detected.
Private key in source	✅ Passed	No private key in source detected.
Database connection URL with embedded credentials	✅ Passed	No database connection url with embedded credentials detected.
Cloud credential in source	✅ Passed	No cloud credential in source detected.
Webhook signing secret in source	✅ Passed	No webhook signing secret in source detected.
OAuth client secret in source	✅ Passed	No oauth client secret in source detected.
JWT signing secret in source	✅ Passed	No jwt signing secret in source detected.
Hardcoded password	✅ Passed	No hardcoded password detected.
Auth middleware removed from route	✅ Passed	No auth middleware removed from route issues detected.
Route protection changed (protected → public)	✅ Passed	No route protection changed (protected → public) issues detected.
Permission / RBAC check removed	✅ Passed	No permission / rbac check removed issues detected.
Required role weakened	✅ Passed	No required role weakened issues detected.
Admin-only route exposed to lower privilege	✅ Passed	No admin-only route exposed to lower privilege issues detected.
Token validation skipped in middleware chain	✅ Passed	No token validation skipped in middleware chain issues detected.
JWT verification weakened or changed	✅ Passed	No jwt verification weakened or changed issues detected.
Session expiration / TTL changed	✅ Passed	No session expiration / ttl changed issues detected.
Password reset flow changed	✅ Passed	No password reset flow changed issues detected.
OAuth callback / redirect handling changed	✅ Passed	No oauth callback / redirect handling changed issues detected.
Webhook endpoint missing signature verification	✅ Passed	No webhook endpoint missing signature verification issues detected.
Public route touches private/PII data	✅ Passed	No public route touches private/pii data issues detected.
Code correctness issue	✅ Passed	No additional explanation was reported.
Runtime error risk	✅ Passed	No additional explanation was reported.
Resource leak risk	✅ Passed	No additional explanation was reported.
Data integrity risk	✅ Passed	No additional explanation was reported.
Maintainability issue	✅ Passed	No additional explanation was reported.
Co-change coupling	✅ Passed	No additional explanation was reported.
Redundant alias / duplicate import	✅ Passed	No additional explanation was reported.
Redundant type construct	✅ Passed	No additional explanation was reported.
Simplifiable code	✅ Passed	No additional explanation was reported.
Unnecessary type assertion	✅ Passed	No additional explanation was reported.
Module smell	✅ Passed	No additional explanation was reported.
Excessive complexity	✅ Passed	No additional explanation was reported.
Dead export (no callers)	✅ Passed	No additional explanation was reported.
Code duplication / DRY violation	✅ Passed	No additional explanation was reported.

_{This comment is updated automatically whenever Autter reviews a new PR revision.}

[autter-dev]

⚠️ 3 unconfirmed finding(s) — flagged by a detector but not proven by Autter's verification pass

Inline comments are reserved for findings that survived verification. These are plausible but could not be confirmed from the available context, so they are listed here as FYIs instead — review the ones that look real to you.

• 🟡 Missing linked tracker issue (risk 49/100) — docs/GETTING-STARTED.md:84 — The provided PR title contains no linked tracker issue, but the PR body is not provided, so it is not possible to verify the finding's claim that neither the title nor body references an issue.
• 🟡 Missing linked tracker issue (risk 35/100) — README.md:57 — No linked issue is shown in the supplied PR context, but the actual PR description and repository policy requiring a linked tracker issue were not provided, so the claimed policy violation cannot be proven from the evidence.
• 🟡 Missing CODEOWNERS reviewer approval (risk 45/100) — README.md:57 — The supplied files show no CODEOWNERS entry or approval metadata, but they cannot establish whether the repository requires approval for these documentation paths or whether an approving review exists outside the provided content.

[autter-dev]

Autter completed PR review for #15: 3 finding(s) remain below the merge-blocking bar, so this review stays neutral rather than approving. See the findings below; the task checklist follows as the review's final comment.

[autter-dev]

Autter's deep review traced 1 finding(s) to file(s) this PR does not change — they can't be shown as inline comments, but the change still affects them:

🔴 [deterministic] Build failed: example-express-app (risk 80/100)

examples/express-app/package.json:1 · build_failure

npm run build failed in examples/express-app — this PR breaks the example-express-app build.

What happened: The example-express-app workspace does not define a build script in its package.json, so npm run build has nothing to execute.

How to fix: Add a build script to examples/express-app/package.json with the appropriate build command, or update the CI check to invoke a script that already exists. Verify available scripts with npm run --workspace=example-express-app@0.0.0.

Build output

npm error Lifecycle script `build` failed with error:
npm error workspace example-express-app@0.0.0
npm error location /tmp/autter-agentic-jG08QB/examples/express-app
npm error Missing script: "build"
npm error
npm error To see a list of scripts, run:
npm error   npm run --workspace=example-express-app@0.0.0

[autter-dev]

🧪 Autter test run

Autter executed the automated checks against 91713cd5.

Scope	Command	Result
@autter/otlp-ingester	npm run test	⏭️ skipped (missing toolchain)

Declared tests: 4 test file(s) found — 0 ran, 0 not observed in suite output, 4 did not run.

⚠️ Test cases that did not run

• ⛔ packages/otlp-ingester/src/fingerprint.test.ts (3 cases) — its suite was skipped (missing toolchain)
• ⛔ packages/otlp-ingester/src/normalize.test.ts (4 cases) — its suite was skipped (missing toolchain)
• ⛔ packages/otlp-ingester/src/server.sink.test.ts (2 cases) — its suite was skipped (missing toolchain)
• ⛔ packages/otlp-ingester/src/sink.test.ts (9 cases) — its suite was skipped (missing toolchain)

Test plan (from the PR description)

• ✅ Review the updated README instructions and confirm they identify the user's application repository as the location for instrument.cjs. — verified by agent execution
• ✅ Review the getting-started guide and confirm the repository distinction is clear in both the setup and backend instrumentation steps. — verified by agent execution
• ✅ Follow the documented commands against a sample application to verify the instructions remain internally consistent. — verified by agent execution

🤖 Agent-executed checks

✅ Review the updated README instructions and confirm they identify the user's application repository as the location for instrument.cjs.
Ran: node .autter/scratch/verify-docs.cjs

documentation assertions passed; README backend section says instrument.cjs is created in your own app next to its entry point.

✅ Review the getting-started guide and confirm the repository distinction is clear in both the setup and backend instrumentation steps.
Ran: node .autter/scratch/verify-docs.cjs

documentation assertions passed; guide states the clone only runs the ingester, code is never added to that checkout, and backend setup/instrument.cjs happen in your application's repository, explicitly not the autter-runtime checkout.

✅ Follow the documented commands against a sample application to verify the instructions remain internally consistent.
Ran: npm install --no-package-lock --ignore-scripts /tmp/autter-agentic-XwnLqg/.autter/scratch/autter-runtime-node-1.0.0.tgz; AUTTER_RUNTIME_KEY=autter_rt_disposable AUTTER_ENDPOINT=http://127.0.0.1:9 NODE_ENV=test GIT_SHA=sample node --require ./instrument.cjs server.js; curl --fail --silent http://127.0.0.1:3127/health

npm install completed; preloaded sample app logged 'sample app listening on 3127'; curl returned {"ok":true}; command exit=0.

⬜ items could not be verified automatically and still need a manual check.

[autter-dev]

Autter blocked this PR after its agentic checks (build/test/deep scans) completed: build_failure; 1 confirmed correctness/runtime finding(s). See the findings below and the full PR review for details.

[autter-dev]

🔴 Autter review in progress — running security, correctness & dependency checks on this PR. Follow live step-by-step progress on the autter/review-gate check in the merge box. Merge is blocked until the gate completes; Autter approves automatically when the review comes back clean, and releases this hold with a neutral review when it finds non-blocking issues.

[autter-dev]

⚠️ 2 unconfirmed finding(s) — flagged by a detector but not proven by Autter's verification pass

Inline comments are reserved for findings that survived verification. These are plausible but could not be confirmed from the available context, so they are listed here as FYIs instead — review the ones that look real to you.

• 🟡 Missing linked tracker issue (risk 49/100) — docs/GETTING-STARTED.md:93 — The PR title contains no linked tracker issue, but the PR body is not provided, so the claim that neither title nor body references an issue cannot be established from the supplied evidence.
• 🟡 Missing CODEOWNERS reviewer approval (risk 45/100) — docs/GETTING-STARTED.md:93 — The actual CODEOWNERS contents and review records are not included, so the asserted absence of a matching approving review and whether such approval is required cannot be independently verified.

[autter-dev]

Autter completed PR review for #15: 3 finding(s) remain below the merge-blocking bar, so this review stays neutral rather than approving. See the findings below; the task checklist follows as the review's final comment.

[autter-dev]

Autter task list

• @sagnik11 Create and link a tracker issue for the documentation change (README.md, docs/GETTING-STARTED.md) - sagnik11 should create a tracker issue describing the instrument.cjs placement clarification and link it from the PR title or body, including references to README.md and docs/GETTING-STARTED.md.
• @sagnik11 Add documentation ownership and obtain approval (docs/GETTING-STARTED.md) - sagnik11 should add the appropriate documentation owner to CODEOWNERS and obtain an approving review for docs/GETTING-STARTED.md before merging.
• @sagnik11 Verify the instrumentation instructions end to end (README.md, docs/GETTING-STARTED.md) - sagnik11 should follow the README and getting-started commands against a sample application, confirming that the app repository contains instrument.cjs, the cloned autter-runtime checkout only runs the ingester, and backend instrumentation starts successfully.
• @sagnik11 Audit related package guidance for repository-path consistency (packages/otlp-ingester/README.md, packages/runtime-node/README.md, packages/runtime-next/README.md) - sagnik11 should review the linked runtime and ingester README files for conflicting instructions about where users install packages or create instrument.cjs, updating any inconsistencies found.

Generated from PR diff, blast radius, and context.

Issues found

1. Missing linked tracker issue · risk 49/100 · docs/GETTING-STARTED.md:93
2. Missing CODEOWNERS reviewer approval · risk 45/100 · docs/GETTING-STARTED.md:93
3. Missing linked tracker issue · risk 40/100 · README.md:57

🛠 Fix options

Check one option and Autter will start a fix run for the unresolved issues above.

• One PR with all unresolved fixes
• One independent PR per unresolved issue

Checking a box triggers the fix run immediately — Autter comments back with the issues being fixed and the branch created for each.