feat(tui): guide first-time users to project creation

[nborges-aws]

PR also includes changes from @tejaskash PR #2437

Description

Add UI hints to TUI landing page, guiding users to project creation if one cannot be auto-deteced.

• Checks whether the current directory is inside an AgentCore project. The TUI launch prefetches this before the first frame, so the menu never shifts.
• If no project detected: show informational alert on the TUI landing page, and render ← start here hint beside create. The root menu lists create, the resource commands (gateway, harness, identity, memory, payment, runtime), and feedback, config, and update. Project commands and eval are hidden.
• If a project is detected: hide both prompts and list every command except create.
• Add reusable Alert and left-arrow glyph support, plus an ASCII fallback

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• bun run test (3658 pass, 0 fail)
• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Small, focused change. The Alert component and optionHints/banner additions to RouterScreen are cleanly separated, and RootScreen's use of useQuery matches the existing pattern in ProjectGate/useProject. Tests exercise real routing and only override projectManager.resolve (the correct I/O seam), asserting on rendered frame content rather than internals — no excessive mocking. The leftArrow glyph is added in both the unicode and ASCII tables, so tests remain deterministic across terminals. This is a UI hint on top of an existing screen, so no new telemetry seems warranted.

Nothing blocking — LGTM.

Minor observations (non-blocking, take or leave):

• RootScreen uses queryKey: ["project-detected", from] while useProject uses ["project", from], so project resolution runs twice when the user drills into a project screen. Sharing the same key (or exposing useProject in a non-throwing variant) would avoid the duplicate FS read, but at gcTime: 0 the cost is negligible.
• If projectManager.resolve rejects, the banner is silently suppressed. Acceptable for a hint, just noting it.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.24%. Comparing base (773cb64) to head (044cf0c).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@            Coverage Diff            @@
##           refactor    #2433   +/-   ##
=========================================
  Coverage     97.24%   97.24%           
=========================================
  Files           617      620    +3     
  Lines         43848    43920   +72     
=========================================
+ Hits          42639    42711   +72     
  Misses         1209     1209           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[AlexanderRichey]

Hmm I don't think this logic should be in the router. The router is supposed to be general.

[AlexanderRichey]

The previous impl should be fine:

  createProjectHandlers(core, io).forEach((handler) => {
    root.handler(handler);
  });

We just need to filter the project commands in the router, which we can do since we have the context there.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[notgitika]

Could we limit this project check to the root menu? right now, a malformed agentcore.json can also prevent unrelated commands like agentcore runtime list from opening