docs: define Applications and isolated Environments

[rohittcodes]

Applications currently describe deployment environments, which conflicts with the intended product hierarchy. Record the accepted model: Applications own Agent and Workflow definitions; Development and Production Environments own deployed versions and runtime authority.

Update the domain glossary, supersede ADR 0004 with ADR 0022, and record shared Connection access/reviewer ownership and the permitted local reset boundary. This PR records the target model only; schema, API, SDK and UI implementation remain tracked in #181. It does not close that issue.

Validation: pnpm lint, pnpm typecheck and pnpm format:check passed. No database or runtime code changed.

Summary by CodeRabbit

• Documentation
  • Clarified that Applications own Agent and Workflow definitions, while Environments manage deployed versions, runtime settings, keys, Connections, and access.
  • Documented Environment-scoped sessions and Conversations, including handling by Agents or Workflows.
  • Explained access grants and reviewer approval for shared Connections, and authorization requirements for proposed actions.
  • Added the target organization model and marked an earlier architecture decision as superseded.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
getlinea-docs	Error		Oct 3, 2026 11:07am UTC

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 797e0a97-6207-44ed-adb8-31e9eee8ec3d

📥 Commits

Reviewing files that changed from the base of the PR and between b792f50 and 3934ec6.

📒 Files selected for processing (3)

• CONTEXT.md
• docs/adr/0004-treat-applications-as-deployed-security-boundaries.md
• docs/adr/0022-own-definitions-by-application-and-authority-by-environment.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The documentation now defines Applications as owners of Agent and Workflow definitions and Environments as runtime and isolation boundaries. It updates key, session, Conversation, Connection, consent, and policy definitions, adds ADR-0022, and marks ADR-0004 superseded.

Changes

Application and Environment model

Layer / File(s)	Summary
Organization and isolation boundaries docs/adr/0022-own-definitions-by-application-and-authority-by-environment.md, CONTEXT.md, docs/adr/0004-treat-applications-as-deployed-security-boundaries.md	ADR-0022 defines Application ownership of Agent and Workflow definitions, Environment runtime ownership and isolation, reset constraints, and excluded resources. CONTEXT.md defines Agents, Workflows, Applications, Environments, Deployments, and Environment Keys. ADR-0004 now identifies ADR-0022 as superseding it.
Environment runtime access CONTEXT.md	Sessions, Conversations, Connections, access grants, reviewer assignments, consent, and Connector Access Policy are now defined in Environment scope.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 3934e

This documentation clarifies which resources belong to Applications and Environments without changing runtime behavior. No concrete issue remains in the supplied review context, so it is ready to merge subject to normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 3934e

The target model preserves production isolation, protected identity configuration, and human consent requirements. No introduced security weakness is established. Implementation is explicitly deferred, however, and authorization behavior during revocation, concurrent execution, and reset remains unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — The intended runtime credential boundary is one Environment, not all Environments in an Application. Shared provider-account authority is available only through Environment-scoped access grants and reviewer assignments. These are documented exposure limits, not verified production enforcement.

Trust Boundaries and Controls

• observed — The pre-existing trust decision identifies compromised-backend replacement of an identity trust anchor as a route to forged End-User Sessions and defeated approval boundaries. It requires an interactive workspace-admin session with recent reauthentication for trust and key-management changes. ADR 0022 carries that protection to Environment, while the new Environment Key contract explicitly forbids identity-trust changes.

Resilience and Maintainability Implications

• inferred — The recorded static controls do not establish authorization throughout completion and recovery. The inspected target documentation does not specify execution-time handling of revoked grants or reviewer assignments, duplicate or concurrent side effects, pending-approval invalidation, or partial reset recovery. These remain deferred implementation questions, not verified vulnerabilities introduced by this PR.

Hardening Proposals

• proposed — During the deferred implementation, specify race-safe authorization revalidation before external effects, duplicate-effect handling, and invalidation of pending authority during revocation or Environment reset. Include interruption and partial-failure recovery so stale grants, reviewer assignments, sessions, or approvals cannot survive a boundary replacement unintentionally.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main documentation change: defining Applications and isolated Environments.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud