Context
Sync profiles today pin to a connection in one of two ways:
-
Hardcoded connectionKey (legacy) — "connectionKey": "live::gmail::default::abc123". Breaks silently when the user re-auths and a new key is generated.
-
Late-bound connection ref (v1.41.0) — "connection": { "platform": "gmail" }. Resolves at runtime, but fails when the user has multiple connections for the same platform:
Multiple "gmail" connections found. Add a "tag" field to disambiguate.
There's no clean way to wire a profile to a specific connection among several on the same platform without falling back to the stale connectionKey approach.
Proposed pattern: named connections
-
Tag connections at creation time:
one add gmail --tag personal
one add gmail --tag work
-
Sync profiles reference by platform + tag:
{
"connection": { "platform": "gmail", "tag": "personal" }
}
-
If only one connection exists for a platform, tag stays optional (current behavior).
-
one add gmail --tag personal on an existing tagged connection refreshes it in place rather than creating a duplicate.
What this eliminates
- Stale connection keys in profiles after re-auth
- Duplicate connections from
one add on an existing platform
- The need for external resolvers (several users have built wrapper scripts for this)
- Ambiguity when multiple connections exist for the same platform
Scope
one add <platform> --tag <name> — create or refresh a tagged connection
one connection list — show tag column
connection: { platform, tag } — recognized in sync profile schema
- Documentation updates:
guide sync, skills/one/SKILL.md, README
Raised in knowledge repo issue withoneai/knowledge#69 — breaking out here since it's CLI-scoped.
Context
Sync profiles today pin to a connection in one of two ways:
Hardcoded
connectionKey(legacy) —"connectionKey": "live::gmail::default::abc123". Breaks silently when the user re-auths and a new key is generated.Late-bound
connectionref (v1.41.0) —"connection": { "platform": "gmail" }. Resolves at runtime, but fails when the user has multiple connections for the same platform:There's no clean way to wire a profile to a specific connection among several on the same platform without falling back to the stale
connectionKeyapproach.Proposed pattern: named connections
Tag connections at creation time:
Sync profiles reference by
platform+tag:{ "connection": { "platform": "gmail", "tag": "personal" } }If only one connection exists for a platform,
tagstays optional (current behavior).one add gmail --tag personalon an existing tagged connection refreshes it in place rather than creating a duplicate.What this eliminates
one addon an existing platformScope
one add <platform> --tag <name>— create or refresh a tagged connectionone connection list— show tag columnconnection: { platform, tag }— recognized in sync profile schemaguide sync,skills/one/SKILL.md, READMERaised in knowledge repo issue withoneai/knowledge#69 — breaking out here since it's CLI-scoped.