Document OpenKhodam config model and workspace memory

[khodam666]

Context

While exploring Google Docs workspace integration, we realized the config model needs clearer product and implementation boundaries before we add more durable state.

We paused the explicit Google Doc attachment/resource-binding PR because the UX felt too config-first. The more natural model may be that OpenKhodam remembers docs the user mentions, opens, previews, or works with, then surfaces them near the work area rather than in project navigation.

Current config layers

• App/user config

  • Global/user-level settings.
  • Owns Google OAuth account, tokens, scopes, and other secrets.
  • Lives in app userData.
  • Must never be committed.

• Project/workspace memory

  • Project-level remembered resources, such as Google Docs used by the project.
  • Could live under .openkhodam/ later.
  • Should contain pointers only, not credentials.
  • Google file IDs/URLs are not OAuth secrets, but may still be sensitive.

• Session state

  • Current/working doc for a specific chat/session.
  • Useful for reopening a session into the same working context.
  • Could become noisy if stored in committed project files.

• Generated runtime config

  • Implementation artifact generated by OpenKhodam for OpenCode/runtime bootstrapping.
  • Not user-authored configuration.

Product direction to consider

Avoid making users attach/configure docs up front. Prefer an organic workflow:

1. User mentions, opens, or works with a Google Doc.
2. OpenKhodam remembers it for the project/session.
3. The right/main pane shows current and recently used docs.
4. The agent can use the current doc context.

The left sidebar should remain navigation-focused: projects, sessions, status. Google Docs/resources likely belong in the right/main pane with the work surface and future preview.

Implementation direction

We should avoid separate ad hoc read/write implementations for each config file. Instead, create one shared config utility for JSON-backed config:

• read JSON
• normalize/default missing or malformed values
• atomic write via temp file + rename
• file mode/permissions where relevant
• clear distinction between secret and non-secret config

Specific config stores should only define:

• path
• default value
• normalizer/schema
• secret/non-secret expectations

Open questions

• What state should be app-global vs project-local vs session-local?
• Should project memory be committed by default, local-only by default, or split into shared/local files?
• Should session-current-doc state live in project memory, app userData, or OpenCode session metadata?
• What should count as a document being mentioned/remembered?
• How should the UI expose remembered docs without making users manage config manually?
• How much of this should be implemented before we have Google Docs preview/live-edit traction?

Acceptance criteria

• Document the config model and ownership boundaries.
• Identify secret vs non-secret config locations.
• Propose one shared atomic JSON config utility.
• Recommend where project remembered docs and session current-doc state should live.
• Keep the design loose enough to avoid prematurely committing to a workspace abstraction.

[tibudiyanto]

for docs config, it should be deeply integrated with the tool call so that everytime the llm open / read a doc it will be counted as "listed" then UI can render this and modify like unlink

[khodam666]

Effect migration coordination

Tracking the incremental Effect architecture in #97.

For this issue, the ownership model remains unchanged: app config, generated runtime config, and project artifact memory stay explicit and separately owned. The first Effect slice will implement the existing app-config call path as:

IPC/plugin boundary
-> process Effect runtime
-> OpenKhodamConfig service
-> JsonPersistence
-> CrossProcessLock
-> filesystem

This should reuse the current JsonConfigFile responsibilities rather than introduce a competing config framework. It will preserve tolerant normalization, atomic replacement, restrictive modes, and secret boundaries while adding typed failures and transactional cross-process updates.

Project artifact memory remains a later phase after the config pilot proves the persistence abstraction and runtime conventions.