[5/5] Wire announcement maker entry points and setup

[rebova-microsoft]

Description

Make the completed announcement flow discoverable through its skill, prompt, setup defaults, and Maker Profile Quick Action.

Current diff

• Resolve missing deployed titleIds through the announcements provider itself; do not require the landing-page MCP process.
• Map Standard priority labels explicitly: Important is 0, Informational is 1, and unspecified priority defaults to Informational.
• Continue a requested review-only create after a successful unresolved audience lookup, preserving supplied content and leaving unresolved audiences unset. Do not guess group IDs, substitute a previous group, or misreport directory failures as no matches.
• Explain the distinction between opening repairable copies and saving valid actions. Preserve actual action kinds/targets; the backend validates every present action on Draft save as well as Publish.
• Document agent scope, supported credential limitations, structured feature errors versus SDK tool errors, and safe recovery.
• Add only the announcements provider to current shipped defaults. Preserve upstream planner removal and active-interpreter symlink handling.
• Include the announcement Quick Action and bundled 0.4.26 VSIX. The version intentionally advances from 0.4.25 so existing installs are treated as stale and prompted to reinstall for the new Quick Action. Keep upstream release history and reinstall checks.
• Keep setup/title-ownership tests independent of collection order and complete the feature CI/routing coverage.

Feature contract

Announcement scope is the authenticated tenant plus the selected deployed titleId, not all agents. A matching scoped widget/backend is required. No copy-title parameter, extra rename write, model-visible mutation, or recovery-envelope field is added.

Stack and dependency

This is slice 5/5. Head: users/rebova/org-announcements-review-maker. Base: users/rebova/org-announcements-review-runtime. The current diff is only this slice against its immediate predecessor; these are stacked review chunks, not parallel PRs against the integration branch.

Bootstrap prerequisite: #262 merged into release/planner-landing-page on September 10, 2026. This stack remains pinned to cacb1bec056428809f1ccb0383561190d516bee4, which is an ancestor of merge commit 8a04f5f40f334e729a3497877edca655730f1be2. Unchanged prerequisite work is excluded from this slice. No rewrite is needed solely to account for that merge. The future release target remains TBD and its final promotion baseline must be confirmed separately.

Testing

740 offline Python tests and 44 extension tests passed on the integrated stack, covering the announcement provider and setup/maker routing, including the priority, unresolved-audience, repairable-copy, and committed-refresh regressions. Extension source and the bundled VSIX are unchanged by these corrections.

Local execution used Python 3.13.15. No local Python 3.11 or live-service acceptance is claimed.

Readiness

• Paired hosted-widget and real-backend integration remain required before rollout; mock acceptance is not backend validation.
• This is not release approval and performs no deployment. The future release branch is still TBD.
• The prerelease integration branch remains baseline-only until reviewed chunks are merged through the normal review process.
• Relevant offline tests pass.
• Python 3.11 CI results.
• Authorized live integration and end-to-end validation.

[rebova-microsoft]

File-by-file walkthrough: make the feature available to makers

The earlier PRs supply the clients and MCP tools. This slice supplies the ways a maker reaches them: command routing, setup registration, instructions for the chat agent, and the Maker Profile button/package.

These comments explain the 19 changed text files. The VSIX is binary, so its explanation is attached at file level rather than to an invented source line. This is an explanatory review, not an approval or a resolution of existing feedback. Registration and documentation do not establish that the paired widget/backend is deployed.

[rebova-microsoft]

Walkthrough — include maker routing in the feature's CI coverage.

This adds the existing foundation/setup-router suite to the announcements job. That suite now checks the command, skill, menu, dependency-install guidance, and separate-provider routing introduced by this slice.

The job already exists from earlier chunks; this is one additional test selector, not another workflow or branch-policy change.

[rebova-microsoft]

Walkthrough — make installer documentation match the button rail.

The Maker Profile's advertised Quick Actions now includes Post an announcement. This is a one-line documentation update so someone reading the setup guide knows the entry point exists.

It does not change the installer or install a second application; the actual button and packaged extension changes are elsewhere in this PR.

[rebova-microsoft]

Walkthrough — route announcement intent to its own workflow.

These instructions tell the chat agent to read the announcement skill for announcement requests and calls to ess-org-announcements. They also add the command to the kit's grounding sources and routing table.

The important boundary is explicit: missing deployed titleId values are resolved through the announcement provider's own read-only tools. Announcements does not start or call the landing-page MCP process, even though both providers share Python discovery code underneath. Landing-page configuration remains a separate flow.

This Markdown affects runtime agent behavior; it is not merely a feature-design document. The explicit target identifies the deployed agent, while tenant context and authorization remain with the authenticated service path.

[rebova-microsoft]

Walkthrough — expose the command in the maker's menu.

This adds /org-announcements and a short description scoped to the selected deployed ESS agent. It makes the new flow discoverable alongside /landing-page without combining the two workflows.

The menu is an entry point only; the dedicated prompt and skill own the behavior after the maker chooses it.

[rebova-microsoft]

Walkthrough — a thin slash-command entry point.

This new prompt gives /org-announcements an agent-mode entry point and delegates directly to src/skills/org-announcements/SKILL.md.

It deliberately does not duplicate configuration reading, authentication, or announcement logic here. Those rules live in the skill so slash-command use and natural-language announcement intent follow the same instructions.

[rebova-microsoft]

Walkthrough — keep the command, instructions, setup, and CI connected.

The added cases check that the prompt delegates to the skill, setup/server guidance is present, target discovery stays on the announcement provider, tenant/agent scope is disclosed, and chat is instructed to open once rather than duplicate the widget's writes.

They also check dependency-install guidance, registration across entry points, separate CI jobs, the approved branch filters, and the distinction between SDK tool errors and coded feature errors.

Several checks intentionally assert normalized instruction text. They guard the shipped agent guidance, not the model's behavior in a real conversation; deliberate wording changes need matching assertions. They do not replace the later local/E2E exercise.

[rebova-microsoft]

Walkthrough — document the new Quick Action in the extension guide.

This one-line addition describes Post an announcement as a guided authoring entry point alongside the other Maker Profile actions.

It changes the extension's feature list only. The click routing lives in extension.js, and the announcement form itself remains in Vorpal.

[rebova-microsoft]

Walkthrough — describe the contents of the updated 0.4.25 POC package.

These release notes add the setup-gated announcement Quick Action, clarify that scope/limits apply per tenant and agent, and tell the maker to reinstall the reviewed package to refresh the rail/tutorial.

The existing 0.4.25 history is retained; this PR replaces the package contents without increasing that version. The notes are not a claim that a backend rollout or feature deployment occurred.

[rebova-microsoft]

Walkthrough — a button that starts the same chat flow, not another editor implementation.

The new announcements action is gated on setup and sends Create an organization announcement into chat. The normal instruction routing then selects the announcement skill and opens the widget; the button does not call Save or publish directly.

The other additions give the built-in tutorial an Announcements navigation link and section. Existing actions stay in place. This file owns the Maker Profile entry point and tutorial, while the visual announcement form remains in Vorpal.

[rebova-microsoft]

Walkthrough — guard the ninth action's routing and scope wording.

The action-count expectation changes from eight to nine. New assertions check the announcement label, chat query, description, and setup prerequisite, plus tutorial wording that identifies per-agent scope rather than promising a tenant-wide announcement collection.

These are extension structure/routing checks. They do not send the chat request, exercise the Vorpal form, or publish an announcement.

[rebova-microsoft]

Walkthrough — the installable Maker Profile package.

A VSIX is the packaged extension makers install, so this binary changes alongside the source that adds the announcement Quick Action and tutorial. The filename and manifest version remain 0.4.25; the archive grows from 30,666 to 31,073 bytes.

The packaged extension.js and package.json match the corresponding source files at this PR's commit. This is a package update, not a source-code hunk or a backend deployment, so the explanation is attached to the file rather than an invented line number. The changelog calls for reinstalling the reviewed package to pick up its changed contents.

[rebova-microsoft]

Commit 5c7e56e makes the priority mapping explicit, keeps requested review-only drafts opening after unresolved audience lookup, and distinguishes repairable copy content from backend-valid actions. The branch includes the contracts/runtime follow-ups through merge commits. No test-harness configuration, private fixture data, or live bug-bash checkout changes are included.

[Dawn Jeong (daeunJe0ng)]

[copilot-review] Reviewed at head 30b9546. Verdict: Approve with one should-fix. The maker wiring, docs, scope, and CI coverage are correct, and there are no secrets in the text diff. No external reviews exist yet, so there was no prior reviewer feedback to reconcile (the existing review entries are the author's own file walkthroughs).

Design verdict

Right layer for a 5/5 discoverability slice: skill, prompt, setup defaults, docs, CI, and the Maker Profile entry point, with the actual authoring still owned by the MCP tools from PR 272.

Should-fix

The bundled ess-maker-profile VSIX binary changed to add the "Post an announcement" Quick Action, but tools/ess-maker-profile/extension/package.json still reports "version": "0.4.25" and the change is logged under the existing 0.4.25 entry. The extension's self-update only treats an install as stale when repoVersion > installedVersion, so a maker already on 0.4.25 who pulls the repo and reloads keeps the old extension without the new button. The one-shot installer uses --force, so a reinstall recovers, but the in-extension update path will not prompt because both versions are equal. Bump the extension version and rebuild the VSIX, or change stale-detection to compare a build hash when the bundled binary changes.

What is good

Verified directly: priority mapping is exact (Important is 0, Informational is 1, unspecified defaults to Informational); review-only create continues after an unresolved audience lookup without guessing group IDs or misreporting a directory failure as no matches; scope stays tenant plus selected titleId with no model-visible mutation added; setup defaults keep the upstream planner removal and the active-interpreter symlink handling; and the setup tests are written to be collection-order independent.

Verification

Read the full diff and the relevant head blobs at 30b9546 (skill, copilot-instructions routing, setup defaults and materializer, Maker Profile extension and package and changelog, setup tests). Did not decode the VSIX binary and did not run tests or check out the branch. No new commits or external comments since this review.

[Dawn Jeong (daeunJe0ng)]

[copilot-review] Re-reviewed at HEAD 2f53913. Verdict: Approve with nits.

The prior should-fix (bundled VSIX changed but version stayed 0.4.25, so the in-extension stale-check would not prompt existing installs) is resolved by 2f53913: package.json is now 0.4.26, a 0.4.26 CHANGELOG entry is added, the bundled VSIX is ess-maker-profile-0.4.26.vsix, and both test_maker_profile_vsix.py and extension.test.js guard the bump.

Verification: node extension.test.js → 44/44 pass; the maker-slice pytest set (test_foundation_setup_router.py, test_maker_profile_vsix.py, test_setup_preserves_title_id.py, test_mcp_config.py) → 68/68 pass. Extracted the 0.4.26 VSIX and confirmed it contains the "Post an announcement" action and that extension.js/changelog match source byte-for-byte.

Should-fix (no code change): the PR description still says "bundled 0.4.25 VSIX without rebuilding or increasing its version." HEAD does the opposite (bumps to 0.4.26, replaces the VSIX, adds a 0.4.26 CHANGELOG entry). The code is correct — please update the description so it reflects what is shipped.

One nit and one question are left as inline comments.

No external reviewer feedback to reconcile; the other review entries are the author's own file-by-file walkthroughs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Resolve the setup dependency path, shared module importer usage, and 0.4.25 VSIX/version mismatch before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2 · 1

Open (3)

• Use isolated loader for directory client imports · New
• Reconcile manifest version with 0.4.25 release constraint · New
• Add separators to limit descriptions · New

What changed in this PR

Adds organization announcement authoring to ESS Maker through skills, prompts, setup defaults, documentation, Quick Actions, and CI coverage.

Changes:

• Adds announcement routing, scope, audience, priority, and recovery guidance.
• Registers provider defaults and setup dependencies.
• Adds Quick Action, VSIX, setup, routing, and CI coverage.

File	Summary
tools/​ess-maker-profile/​README.md	Documents the announcement Quick Action.
tools/​ess-maker-profile/​extension/​package.json	Updates extension metadata.
tools/​ess-maker-profile/​extension/​extension.test.js	Tests the announcement action and package behavior.
tools/​ess-maker-profile/​extension/​extension.js	Adds the announcement action and tutorial content.
tools/​ess-maker-profile/​extension/​CHANGELOG.md	Records the feature release.
tests/​setup/​test_foundation_setup_router.py	Adds routing, setup, and CI assertions.
tests/​scripts/​test_setup_preserves_title_id.py	Stabilizes setup-module loading.
tests/​scripts/​test_mcp_config.py	Tests announcement default materialization.
tests/​scripts/​test_maker_profile_vsix.py	Verifies bundled VSIX consistency.
tests/​mcp/​agentconfig_org_announcements/​test_setup_materialization.py	Tests provider materialization and token-cache behavior.
solutions/​ess-maker-skills/​src/​skills/​org-announcements/​SKILL.md	Defines announcement orchestration and recovery rules.
solutions/​ess-maker-skills/​src/​skills/​onboarding/​step2.md	Adds announcement onboarding guidance.
solutions/​ess-maker-skills/​src/​skills/​onboarding/​step1.md	Installs announcement dependencies.
solutions/​ess-maker-skills/​src/​skills/​onboarding/​SKILL.md	Updates setup-complete guidance.
solutions/​ess-maker-skills/​README.md	Documents announcement functionality.
solutions/​ess-maker-skills/​.vscode/​mcp.defaults.json	Registers the announcement MCP server.
solutions/​ess-maker-skills/​.github/​prompts/​org-announcements.prompt.md	Adds the announcement prompt entry point.
solutions/​ess-maker-skills/​.github/​prompts/​menu.prompt.md	Adds the command to the menu.
solutions/​ess-maker-skills/​.github/​copilot-instructions.md	Routes announcement requests to the skill.
setup/​README.md	Documents the Quick Action.
.github/​workflows/​ci.yml	Adds VSIX and announcement feature CI coverage.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Resolve the onboarding completion path and strengthen the title-reuse regression assertion; also reconcile the conflicting save-status guidance.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2

Open (2)

• Update setup handoff to expose the announcement entry point · New
• Strengthen assertion to enforce title-reuse behavior · New

Resolved since last review (3)

• Reconcile manifest version with 0.4.25 release constraint
• Use isolated loader for directory client imports
• Add separators to limit descriptions

[Copilot]

Copilot review overview

🔵 Needs a closer look

The completed-state setup path may miss the required announcements dependency, and the cache regression test does not exercise the announcements server.

Review effort: Lite
Findings: None

Resolved since last review (2)

• Strengthen assertion to enforce title-reuse behavior
• Update setup handoff to expose the announcement entry point

Previously missed (1)

In code that hasn't changed since last review

Test announcement server token cache configuration

tests/​mcp/​agentconfig_org_announcements/​test_setup_materialization.py:246

This regression test never imports the announcements server or inspects its cache configuration; locations is built only from the already-loaded Graph and core constants. If a future server change creates a third token cache under agentconfig_org_announcements/.local, this test would still pass. Exercise the announcement module/server or assert the cache path used by the announcement code so the test guards the behavior named in its title.

[Apurva Banka (apurvabanka)]

Reviewed the full diff, ran the affected pytest suites (733 passed) and the extension tests (44 passed) locally. The wiring is solid and well covered; a few gaps:

Gaps

1. Repo-root redirect list is missing /org-announcements — .github/copilot-instructions.md lines 19–31 enumerate the kit slash-commands that trigger the "wrong folder" redirect. /org-announcements (and an announcement intent hint like "Post an announcement") isn't listed, so a maker who opens the monorepo root and types /org-announcements — or clicks the new Quick Action, which sends "Create an organization announcement" — gets a normal answer instead of the redirect. This PR is exactly the "wire entry points" slice, so it belongs here.

2. Entry-point parity test doesn't cover all surfaces it wired. test_org_announcements_is_registered_across_entry_points checks menu, instructions, step2, foundation, handoff — but not solutions/ess-maker-skills/README.md command table, setup/README.md Quick Actions line, or the extension ACTIONS entry. Those three are the ones most likely to silently drift.

3. Landing-page routing row was weakened without a replacement. | Invoke any tool from the ess-landing-page-config MCP server | → | Invoke a landing-page configuration tool |, while announcements kept the server-named row. Understandable (both servers now expose list_agent_configs/search_agents), but landing-page no longer has a catch-all route by server name; an unrecognized landing-page tool now falls through to a generic flow.

4. CI placement nits. tests/scripts/test_maker_profile_vsix.py runs in the landing-page-config job (it guards the extension package, which is feature-neutral), and tests/setup/test_foundation_setup_router.py — a broad setup-router suite, previously not in CI at all — now runs only inside the org-announcements job. Both are fine today but attach general guards to a feature job that is presumably temporary.

5. Minor, pre-existing class: the "setup already complete" resume path (onboarding/SKILL.md) installs only scripts/requirements.txt, never src/mcp/agentconfig_org_announcements/requirements.txt. It works today only because mcp/pydantic came in with the landing-page install; a maker who never ran /landing-page setup would hit a server that can't start, and the skill's availability check only diagnoses configuration, not missing deps.

[jiuqlo]

Should fix: distinguish renewable cached sign-ins from credentials that require repair. AuthenticationRequired does not always mean a cached credential can be renewed by rerunning the command. For example, acquire_graph_token() reads GRAPH_ACCESS_TOKEN before trying MSAL. I reproduced two consecutive audience searches with a synthetically rejected explicit token: both sent the same rejected credential and returned AuthenticationRequired with retryable: false; neither opened a browser. Missing identity claims or invalid credential files likewise need correction rather than another identical call. This unconditional advice also conflicts with the earlier instruction not to retry when retryable is false. Please limit the rerun guidance to the appropriate cached-MSAL recovery case and explain how to replace or repair explicit credentials. Updating an environment-provided token may require restarting the MCP provider so it receives the new environment, so the blanket prohibition on restarting is misleading. Keep the existing no-replay guidance for committed or indeterminate writes.

[Dawn Jeong (daeunJe0ng)]

[copilot-review]

Approve with nits. This is a clean wiring/docs/tests slice: the announcement entry points are registered across surfaces, auth-recovery guidance is now source-aware, and the earlier review findings are resolved in later commits. Nothing blocking at current head.

Still worth a look (non-blocking):

• Question, solutions/ess-maker-skills/src/skills/org-announcements/SKILL.md: the skill documents a hard contract that the opener call is read-only, titleId is required, and the widget owns all mutations. That boundary is enforced by the MCP server in PR [4/5] Expose the scoped announcement MCP runtime #272 (the base branch), not in this diff. Please confirm [4/5] Expose the scoped announcement MCP runtime #272 actually enforces required-titleId and rejects mutations on the opener path, so the documented guarantee cannot be bypassed.

The parity-test coverage gap (solution README command-table row) and the CI job-placement nits are already captured by another reviewer, so I am not restating them here.

What is good: source-aware auth recovery (SKILL.md lines 464-481) correctly separates renewable cached-MSAL sign-ins from explicit env tokens and malformed-claim credentials, and honors retryable first; the token-cache guard test loads the real announcements server; the resume path now installs the announcements requirements.

Note: commit 65f0ddd ("make auth recovery source-aware") post-dates the earlier approval; I re-reviewed it here and it resolves the outstanding auth-recovery comment.

Not verified: I did not run the pytest suites or extension tests locally, and did not exercise the live widget/MCP backend integration. Review is static plus cross-referencing the VSIX contents and CI dependency wiring.

[Dawn Jeong (daeunJe0ng)]

Looks good to merge for this urgent slice; the entry-point wiring, docs, and tests are consistent and earlier findings are resolved at this head.

Non-blocking follow-ups are in my [copilot-review] comment above; none block merge.