[DavidLeuter]

Short summary

Gives the buddy a map of the Sprintstart app itself, so "where do I create a role?" or "what can I do on this page?" is answered from the app instead of from search_docs, which only knows the project's own material.

• New tool get_app_guide, mounted in both the hire's buddy and team mode.
• AppGuide.kt: a hand-written catalog of every frontend page: where it is, what it is for, how to do things there (in the UI's own labels), who may open it, and per how-to a deep link to the right tab where the page keeps its tab in the URL (e.g. /team-management?tab=roles). Includes the new admin-only "Skills" tab of Access Management.
• Filtered for the caller: by permission group and, for a PM, by the projects they manage (mirrors accessPolicy.ts). What the caller cannot do is listed as "ask X" instead of sending them to a page they can't open (e.g. creating a project is admin-only). A managing PM is told the manager pages only show while a managed project is selected.
• SendBuddyMessageRequest.currentPage (optional): the path the sender is on, so "this page" / "here" can be resolved. Only matched against the catalog, never echoed.
• New UserApi.getPermissionGroup, and a "What can I do here?" suggestion chip.
• AGENTS.md: frontend page, tab or label changes must update AppGuide.kt in the same piece of work.

Checks

• I verified the code makes sense intuitively
• The PR changes affect only this issue, no unrelated/unwanted code changes to other modules/code segments
• CI runs (./gradlew check)
• New logic is unit tested (AppGuideTest, BuddyAppGuideToolsTest, plus executor/team tools/controller/suggestion tests)
• The new functionality is tested manually

Additional notes

Part of a three-repo change; each PR works on its own (the field is optional, the prompt clause only appears when the tool is mounted), but the feature needs all three:

• Backend: Give the buddy a map of the app: get_app_guide #277
• Frontend: Give the buddy a map of the app: get_app_guide sprintstart-frontend#301
• AI: Give the buddy a map of the app: get_app_guide sprintstart-ai#215

Not yet tried end to end with a real model.

🤖 Generated with Claude Code

[kiranfin]

Review

The guide is carefully scoped: it is filtered by the caller's permission group and managed projects, currentPage is only matched against the catalog and never echoed, and the roles, tab parameters (tab, view) and quoted labels I cross-checked against the frontend's accessPolicy.ts and pages line up. I found no blockers. The open points are where the guide can still describe a different set of pages than the user actually has, and where the new currentPage plumbing is not pinned by tests.

🟡 Worth a look

1. Users who finished onboarding are still linked to /onboarding (AppGuide.kt:202-220, BuddyAppGuideTools.kt:603-606)
The page is registered with roles = EVERYONE, and Reader.opens only looks at the role and managerScoped. In the frontend, /onboarding is additionally gated by isOnboardingAccessible (!hasCompletedOnboarding) in AuthGuard and the sidebar, and the sidebar entry also needs an existing path. The guide lists the page under "Pages they can open (link each as Name)", so a finished hire, and in team mode nearly every manager, gets a link to a route that redirects. The "shown until their onboarding is finished" hint in whereToFind is not enough when the model is told to link every entry. Feed the completed flag into Reader and leave the page out (or list it as unavailable) for those users.

2. "Which projects does the PM manage" is derived from membership, with a query per project (BuddyAppGuideTools.kt:556-565)
managedProjectNames takes getUsersByIds(...).projects and runs canManageProject on each one (two queries per call). ProjectManagerService.setManager documents that manager access does not depend on the membership row. A manager whose assignment row is gone is therefore told "They manage no project yet" and loses every manager page in the guide while the backend still treats them as manager. Please ask for the managed projects directly (one UserApi/ProjectMembershipApi method keyed on the manager) instead of filtering the membership list.

3. The currentPage hand-off is only tested at the edges (BuddyService.kt:290,408, BuddyTeamService.kt:158-163, BuddyControllerTest.kt)
Tests cover controller → BuddyService.sendMessageForMe (hire path only), BuddyToolExecutor.execute and BuddyTeamTools.execute, but nothing pins the two middle hops: runToolCall → buddyToolExecutor.execute(call, userId, currentPage) and BuddyTeamService → TeamToolContext(currentPage = …). If either drops the value, every test stays green and "this page" silently stops working. There is also no controller test for teamProjectId + currentPage, and UserApiService.getPermissionGroup is untested (multi-role collapse e.g. PM+HR → HR, no roles → USER, unknown user → null).

🟢 Nits / cleanup

• AppGuide.pageAt compares exactly, so /team-management/ (React Router accepts the trailing slash) is reported as "a page this guide does not describe". trimEnd('/') on the pathname before matching would fix it (BuddyAppGuideTools.kt:581-590).
• A plain member gets every manager and admin how-to in the "Only somebody else can do these" block (about 15 lines on every call, with the manager's click path). Consider listing only the tasks a member could plausibly ask about, or collapsing it to one line per page, to save prompt space.
• For a PM without a managed project, describeDoers(page.roles) yields "the project's manager, HR or an admin", which includes the asker's own role. The extra "manage no project" paragraph covers it, but the wording is confusing.
• Question for the frontend PR: the chip "What can I do on this page?" resolves to the Buddy page itself when pressed on the full /buddy page. Is the chip hidden there, or should Buddy have its own how-to?
• The description says this was not tried end to end with a real model. Since routing between get_app_guide and search_docs rests only on the tool description, one manual run of "how do I create a project?" as PM, HR and admin before merge would be worth it.

Nothing here blocks the merge. Findings 1 and 2 are cheap to fix in this PR; finding 3 is the one I would not leave as a follow-up, because the currentPage plumbing is the new behaviour and has the least coverage.