Payload
{
"action": "labeled",
"issue": {
"url": "https://api.github.com/repos/darkmatter/nixmac/issues/276",
"repository_url": "https://api.github.com/repos/darkmatter/nixmac",
"labels_url": "https://api.github.com/repos/darkmatter/nixmac/issues/276/labels{/name}",
"comments_url": "https://api.github.com/repos/darkmatter/nixmac/issues/276/comments",
"events_url": "https://api.github.com/repos/darkmatter/nixmac/issues/276/events",
"html_url": "https://github.com/darkmatter/nixmac/issues/276",
"id": 4568959556,
"node_id": "I_kwDOSB6EzM8AAAABEFTKRA",
"number": 276,
"title": "[Onboarding] Show illustrated step-by-step instructions for manual setup steps instead of automating them",
"user": {
"login": "czxtm",
"id": 1325802,
"node_id": "MDQ6VXNlcjEzMjU4MDI=",
"avatar_url": "https://avatars.githubusercontent.com/u/1325802?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/czxtm",
"html_url": "https://github.com/czxtm",
"followers_url": "https://api.github.com/users/czxtm/followers",
"following_url": "https://api.github.com/users/czxtm/following{/other_user}",
"gists_url": "https://api.github.com/users/czxtm/gists{/gist_id}",
"starred_url": "https://api.github.com/users/czxtm/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/czxtm/subscriptions",
"organizations_url": "https://api.github.com/users/czxtm/orgs",
"repos_url": "https://api.github.com/users/czxtm/repos",
"events_url": "https://api.github.com/users/czxtm/events{/privacy}",
"received_events_url": "https://api.github.com/users/czxtm/received_events",
"type": "User",
"user_view_type": "public",
"site_admin": false
},
"labels": [
{
"id": 10865918433,
"node_id": "LA_kwDOSB6EzM8AAAACh6jB4Q",
"url": "https://api.github.com/repos/darkmatter/nixmac/labels/Improvement",
"name": "Improvement",
"color": "ededed",
"default": false,
"description": null
}
],
"state": "open",
"locked": false,
"assignees": [],
"milestone": null,
"comments": 0,
"created_at": "2026-06-02T06:14:27Z",
"updated_at": "2026-06-02T06:14:27Z",
"closed_at": null,
"assignee": null,
"author_association": "MEMBER",
"issue_field_values": [],
"type": null,
"active_lock_reason": null,
"sub_issues_summary": {
"total": 0,
"completed": 0,
"percent_completed": 0
},
"issue_dependencies_summary": {
"blocked_by": 0,
"total_blocked_by": 0,
"blocking": 0,
"total_blocking": 0
},
"body": "## Context\n\nSub-issue of [ENG-271](https://linear.app/darkmatterlabs/issue/ENG-271/onboarding-issues-for-normies). Identified during onboarding testing with a non-technical user.\n\nFor setup steps that cannot be fully automated (or where automation is fragile), nixmac should show clear, illustrated instructions rather than trying to do it for the user and potentially failing. Apps like Pear Cleaner demonstrate that a guided manual flow can still feel polished.\n\nThis reduces the attack surface for automation bugs and gives non-technical users confidence at each step.\n\n## Scope\n\n* Identify which onboarding steps are currently \"partially automated but unreliable\"\n* For those steps, replace or supplement with clear UI showing: what to do, a screenshot/illustration, a confirmation button\n* Inspiration: Pear Cleaner's guided flow\n\n## Acceptance Criteria / Gherkin Specs\n\n```gherkin\nScenario: Manual step is presented with a clear illustration and instruction\n Given a setup step that cannot be fully automated\n When the user reaches that step in the onboarding flow\n Then nixmac shows a clear instruction panel with:\n - A title describing the step\n - A screenshot or illustration showing exactly what to do\n - A confirmation button the user presses when done\n And nixmac validates the step was completed before advancing\n\nScenario: User can retry a manual step if they made a mistake\n Given the user is on a manual instruction step\n When they press the confirmation button but the step validation fails\n Then nixmac shows what went wrong\n And the user can retry from the same step without restarting the whole flow\n\nScenario: Illustrated steps are clear to non-technical users\n Given a user with no Nix or terminal experience\n When they follow the illustrated instructions\n Then they can complete the step without needing to reference external documentation\n```",
"reactions": {
"url": "https://api.github.com/repos/darkmatter/nixmac/issues/276/reactions",
"total_count": 0,
"+1": 0,
"-1": 0,
"laugh": 0,
"hooray": 0,
"confused": 0,
"heart": 0,
"rocket": 0,
"eyes": 0
},
"timeline_url": "https://api.github.com/repos/darkmatter/nixmac/issues/276/timeline",
"performed_via_github_app": {
"id": 1658531,
"client_id": "Iv23lia2it3rsjIhboVE",
"slug": "linear-code",
"node_id": "A_kwHOAshhgs4AGU6j",
"owner": {
"login": "linear",
"id": 46686594,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjQ2Njg2NTk0",
"avatar_url": "https://avatars.githubusercontent.com/u/46686594?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/linear",
"html_url": "https://github.com/linear",
"followers_url": "https://api.github.com/users/linear/followers",
"following_url": "https://api.github.com/users/linear/following{/other_user}",
"gists_url": "https://api.github.com/users/linear/gists{/gist_id}",
"starred_url": "https://api.github.com/users/linear/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/linear/subscriptions",
"organizations_url": "https://api.github.com/users/linear/orgs",
"repos_url": "https://api.github.com/users/linear/repos",
"events_url": "https://api.github.com/users/linear/events{/privacy}",
"received_events_url": "https://api.github.com/users/linear/received_events",
"type": "Organization",
"user_view_type": "public",
"site_admin": false
},
"name": "Linear Code",
"description": "",
"external_url": "https://linear.app",
"html_url": "https://github.com/apps/linear-code",
"created_at": "2025-07-24T11:29:06Z",
"updated_at": "2026-04-14T21:31:51Z",
"permissions": {
"actions": "write",
"checks": "read",
"contents": "write",
"deployments": "read",
"issues": "write",
"members": "read",
"merge_queues": "read",
"metadata": "read",
"pull_requests": "write",
"statuses": "read",
"workflows": "write"
},
"events": [
"check_run",
"check_suite",
"commit_comment",
"issues",
"issue_comment",
"member",
"membership",
"organization",
"pull_request",
"pull_request_review",
"pull_request_review_comment",
"pull_request_review_thread",
"repository",
"status",
"sub_issues",
"team",
"team_add"
]
},
"state_reason": null,
"pinned_comment": null
},
"label": {
"id": 10865918433,
"node_id": "LA_kwDOSB6EzM8AAAACh6jB4Q",
"url": "https://api.github.com/repos/darkmatter/nixmac/labels/Improvement",
"name": "Improvement",
"color": "ededed",
"default": false,
"description": null
},
"repository": {
"id": 1209959628,
"node_id": "R_kgDOSB6EzA",
"name": "nixmac",
"full_name": "darkmatter/nixmac",
"private": false,
"owner": {
"login": "darkmatter",
"id": 17834193,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE3ODM0MTkz",
"avatar_url": "https://avatars.githubusercontent.com/u/17834193?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/darkmatter",
"html_url": "https://github.com/darkmatter",
"followers_url": "https://api.github.com/users/darkmatter/followers",
"following_url": "https://api.github.com/users/darkmatter/following{/other_user}",
"gists_url": "https://api.github.com/users/darkmatter/gists{/gist_id}",
"starred_url": "https://api.github.com/users/darkmatter/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/darkmatter/subscriptions",
"organizations_url": "https://api.github.com/users/darkmatter/orgs",
"repos_url": "https://api.github.com/users/darkmatter/repos",
"events_url": "https://api.github.com/users/darkmatter/events{/privacy}",
"received_events_url": "https://api.github.com/users/darkmatter/received_events",
"type": "Organization",
"user_view_type": "public",
"site_admin": false
},
"html_url": "https://github.com/darkmatter/nixmac",
"description": "Home manager and nix-darwin that understands plain English",
"fork": false,
"url": "https://api.github.com/repos/darkmatter/nixmac",
"forks_url": "https://api.github.com/repos/darkmatter/nixmac/forks",
"keys_url": "https://api.github.com/repos/darkmatter/nixmac/keys{/key_id}",
"collaborators_url": "https://api.github.com/repos/darkmatter/nixmac/collaborators{/collaborator}",
"teams_url": "https://api.github.com/repos/darkmatter/nixmac/teams",
"hooks_url": "https://api.github.com/repos/darkmatter/nixmac/hooks",
"issue_events_url": "https://api.github.com/repos/darkmatter/nixmac/issues/events{/number}",
"events_url": "https://api.github.com/repos/darkmatter/nixmac/events",
"assignees_url": "https://api.github.com/repos/darkmatter/nixmac/assignees{/user}",
"branches_url": "https://api.github.com/repos/darkmatter/nixmac/branches{/branch}",
"tags_url": "https://api.github.com/repos/darkmatter/nixmac/tags",
"blobs_url": "https://api.github.com/repos/darkmatter/nixmac/git/blobs{/sha}",
"git_tags_url": "https://api.github.com/repos/darkmatter/nixmac/git/tags{/sha}",
"git_refs_url": "https://api.github.com/repos/darkmatter/nixmac/git/refs{/sha}",
"trees_url": "https://api.github.com/repos/darkmatter/nixmac/git/trees{/sha}",
"statuses_url": "https://api.github.com/repos/darkmatter/nixmac/statuses/{sha}",
"languages_url": "https://api.github.com/repos/darkmatter/nixmac/languages",
"stargazers_url": "https://api.github.com/repos/darkmatter/nixmac/stargazers",
"contributors_url": "https://api.github.com/repos/darkmatter/nixmac/contributors",
"subscribers_url": "https://api.github.com/repos/darkmatter/nixmac/subscribers",
"subscription_url": "https://api.github.com/repos/darkmatter/nixmac/subscription",
"commits_url": "https://api.github.com/repos/darkmatter/nixmac/commits{/sha}",
"git_commits_url": "https://api.github.com/repos/darkmatter/nixmac/git/commits{/sha}",
"comments_url": "https://api.github.com/repos/darkmatter/nixmac/comments{/number}",
"issue_comment_url": "https://api.github.com/repos/darkmatter/nixmac/issues/comments{/number}",
"contents_url": "https://api.github.com/repos/darkmatter/nixmac/contents/{+path}",
"compare_url": "https://api.github.com/repos/darkmatter/nixmac/compare/{base}...{head}",
"merges_url": "https://api.github.com/repos/darkmatter/nixmac/merges",
"archive_url": "https://api.github.com/repos/darkmatter/nixmac/{archive_format}{/ref}",
"downloads_url": "https://api.github.com/repos/darkmatter/nixmac/downloads",
"issues_url": "https://api.github.com/repos/darkmatter/nixmac/issues{/number}",
"pulls_url": "https://api.github.com/repos/darkmatter/nixmac/pulls{/number}",
"milestones_url": "https://api.github.com/repos/darkmatter/nixmac/milestones{/number}",
"notifications_url": "https://api.github.com/repos/darkmatter/nixmac/notifications{?since,all,participating}",
"labels_url": "https://api.github.com/repos/darkmatter/nixmac/labels{/name}",
"releases_url": "https://api.github.com/repos/darkmatter/nixmac/releases{/id}",
"deployments_url": "https://api.github.com/repos/darkmatter/nixmac/deployments",
"created_at": "2026-04-14T00:37:13Z",
"updated_at": "2026-06-01T06:15:50Z",
"pushed_at": "2026-06-02T05:59:46Z",
"git_url": "git://github.com/darkmatter/nixmac.git",
"ssh_url": "git@github.com:darkmatter/nixmac.git",
"clone_url": "https://github.com/darkmatter/nixmac.git",
"svn_url": "https://github.com/darkmatter/nixmac",
"homepage": "https://nixmac.com",
"size": 679049,
"stargazers_count": 5,
"watchers_count": 5,
"language": "Rust",
"has_issues": true,
"has_projects": true,
"has_downloads": true,
"has_wiki": true,
"has_pages": false,
"has_discussions": false,
"forks_count": 1,
"mirror_url": null,
"archived": false,
"disabled": false,
"open_issues_count": 92,
"license": {
"key": "mit",
"name": "MIT License",
"spdx_id": "MIT",
"url": "https://api.github.com/licenses/mit",
"node_id": "MDc6TGljZW5zZTEz"
},
"allow_forking": true,
"is_template": false,
"web_commit_signoff_required": false,
"has_pull_requests": true,
"pull_request_creation_policy": "all",
"topics": [
"home-manager",
"nix",
"nix-darwin",
"nix-flake",
"opencode"
],
"visibility": "public",
"forks": 1,
"open_issues": 92,
"watchers": 5,
"default_branch": "develop",
"custom_properties": {}
},
"organization": {
"login": "darkmatter",
"id": 17834193,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE3ODM0MTkz",
"url": "https://api.github.com/orgs/darkmatter",
"repos_url": "https://api.github.com/orgs/darkmatter/repos",
"events_url": "https://api.github.com/orgs/darkmatter/events",
"hooks_url": "https://api.github.com/orgs/darkmatter/hooks",
"issues_url": "https://api.github.com/orgs/darkmatter/issues",
"members_url": "https://api.github.com/orgs/darkmatter/members{/member}",
"public_members_url": "https://api.github.com/orgs/darkmatter/public_members{/member}",
"avatar_url": "https://avatars.githubusercontent.com/u/17834193?v=4",
"description": ""
},
"enterprise": {
"id": 469843,
"slug": "darkmatter",
"name": "darkmatter",
"node_id": "E_kgDOAAcrUw",
"avatar_url": "https://avatars.githubusercontent.com/b/469843?v=4",
"description": "",
"website_url": "darkmatter.io",
"html_url": "https://github.com/enterprises/darkmatter",
"created_at": "2025-09-07T16:01:00Z",
"updated_at": "2026-05-09T15:34:55Z"
},
"sender": {
"login": "czxtm",
"id": 1325802,
"node_id": "MDQ6VXNlcjEzMjU4MDI=",
"avatar_url": "https://avatars.githubusercontent.com/u/1325802?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/czxtm",
"html_url": "https://github.com/czxtm",
"followers_url": "https://api.github.com/users/czxtm/followers",
"following_url": "https://api.github.com/users/czxtm/following{/other_user}",
"gists_url": "https://api.github.com/users/czxtm/gists{/gist_id}",
"starred_url": "https://api.github.com/users/czxtm/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/czxtm/subscriptions",
"organizations_url": "https://api.github.com/users/czxtm/orgs",
"repos_url": "https://api.github.com/users/czxtm/repos",
"events_url": "https://api.github.com/users/czxtm/events{/privacy}",
"received_events_url": "https://api.github.com/users/czxtm/received_events",
"type": "User",
"user_view_type": "public",
"site_admin": false
},
"installation": {
"id": 131074261,
"node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uMTMxMDc0MjYx"
}
}