Skip to content

Commit f9824f4

Browse files
isadeksisadeks
committed
docs(linear): clarify teammate-onboarding handshake
The 'Inviting teammates' section was missing the prerequisite that the teammate needs their own ABCA account (Cognito user + configured CLI) before they can redeem a Linear invite code. New flow walks through: Admin: invite-user (Cognito) → invite-user <slug> (Linear) Teammate: configure --from-bundle → login → linear link <code> with cross-references to USER_GUIDE.md's 'Joining an existing deployment' for the Cognito-side details. Also corrects the stale 'auto-links the person running the wizard' claim — setup now offers an inline picker (opt-in by admin), not an automatic mapping.
1 parent 7d994b8 commit f9824f4

2 files changed

Lines changed: 44 additions & 12 deletions

File tree

‎docs/guides/LINEAR_SETUP_GUIDE.md‎

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -96,19 +96,35 @@ Apply the trigger label to a Linear issue in the onboarded project. The agent sh
9696

9797
## Inviting teammates
9898

99-
The setup walkthrough auto-links **the person running the wizard**. To onboard additional teammates so they can trigger tasks from Linear:
99+
The setup walkthrough offers an inline self-link picker that lets the **person running the wizard** map their own Linear identity to their Cognito sub. To onboard additional teammates so they can trigger tasks from Linear from their own ABCA accounts, run:
100+
101+
### Admin: generate the invite
100102

101103
```bash
102104
bgagent linear invite-user <slug>
103105
```
104106

105-
The admin picks the teammate from a Linear member picker. The CLI generates a one-time code (24h TTL) and prints a command to send to the teammate (Slack/email/etc). The teammate runs:
107+
The CLI shows a picker of human Linear members in the workspace. After you pick the teammate, it generates a one-time code (24h TTL) and prints a CLI command to send them via Slack/email/etc.
106108

107-
```bash
108-
bgagent linear link <code>
109-
```
109+
### Teammate: redeem the invite
110+
111+
The teammate needs their own ABCA account first (Cognito user + configured CLI). If they don't have one yet:
112+
113+
1. **Admin** runs `bgagent admin invite-user teammate@example.com` to create their Cognito user (see [User guide → Joining an existing deployment](./USER_GUIDE.md#joining-an-existing-deployment) for the full Cognito-side flow).
114+
2. **Teammate** pastes the bundle + password from the admin into:
115+
116+
```bash
117+
bgagent configure --from-bundle <bundle>
118+
bgagent login --username teammate@example.com
119+
```
120+
121+
3. **Teammate** redeems the Linear invite code:
122+
123+
```bash
124+
bgagent linear link <code>
125+
```
110126

111-
The CLI shows them the Linear identity name+email and asks for confirmation **before** writing the mapping row. If the admin picked the wrong member, the teammate sees the mismatch and aborts.
127+
The CLI shows them the Linear identity name+email and asks for confirmation **before** writing the mapping row. If the admin picked the wrong member, the teammate sees the mismatch and aborts. After confirmation, the binding is recorded — the teammate can now apply the trigger label to a Linear issue and it'll fire as a task under their ABCA account (their concurrency, their cost attribution, their notifications).
112128

113129
### Why this two-step handshake
114130

‎docs/src/content/docs/using/Linear-setup-guide.md‎

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -100,19 +100,35 @@ Apply the trigger label to a Linear issue in the onboarded project. The agent sh
100100

101101
## Inviting teammates
102102

103-
The setup walkthrough auto-links **the person running the wizard**. To onboard additional teammates so they can trigger tasks from Linear:
103+
The setup walkthrough offers an inline self-link picker that lets the **person running the wizard** map their own Linear identity to their Cognito sub. To onboard additional teammates so they can trigger tasks from Linear from their own ABCA accounts, run:
104+
105+
### Admin: generate the invite
104106

105107
```bash
106108
bgagent linear invite-user <slug>
107109
```
108110

109-
The admin picks the teammate from a Linear member picker. The CLI generates a one-time code (24h TTL) and prints a command to send to the teammate (Slack/email/etc). The teammate runs:
111+
The CLI shows a picker of human Linear members in the workspace. After you pick the teammate, it generates a one-time code (24h TTL) and prints a CLI command to send them via Slack/email/etc.
110112

111-
```bash
112-
bgagent linear link <code>
113-
```
113+
### Teammate: redeem the invite
114+
115+
The teammate needs their own ABCA account first (Cognito user + configured CLI). If they don't have one yet:
116+
117+
1. **Admin** runs `bgagent admin invite-user teammate@example.com` to create their Cognito user (see [User guide → Joining an existing deployment](/using/overview#joining-an-existing-deployment) for the full Cognito-side flow).
118+
2. **Teammate** pastes the bundle + password from the admin into:
119+
120+
```bash
121+
bgagent configure --from-bundle <bundle>
122+
bgagent login --username teammate@example.com
123+
```
124+
125+
3. **Teammate** redeems the Linear invite code:
126+
127+
```bash
128+
bgagent linear link <code>
129+
```
114130

115-
The CLI shows them the Linear identity name+email and asks for confirmation **before** writing the mapping row. If the admin picked the wrong member, the teammate sees the mismatch and aborts.
131+
The CLI shows them the Linear identity name+email and asks for confirmation **before** writing the mapping row. If the admin picked the wrong member, the teammate sees the mismatch and aborts. After confirmation, the binding is recorded — the teammate can now apply the trigger label to a Linear issue and it'll fire as a task under their ABCA account (their concurrency, their cost attribution, their notifications).
116132

117133
### Why this two-step handshake
118134

0 commit comments

Comments
 (0)