Test build: issue workflow and site updates

[markmhendrickson]

This draft PR prepares a test-build branch for the issue workflow migration, guest access controls, MCP local-port handling, and the refreshed skills/use-case documentation surfaces. It is intentionally a PR-based test build, not a GitHub Release or npm publish.

Highlights

• Issue reporting moves into the main Neotoma workflow. New issues CLI/service surfaces, GitHub sync helpers, auto-label workflow support, and issue-oriented Inspector pages replace the legacy feedback-admin path.
• Guest access policy becomes inspectable and enforceable. access CLI support, access-policy services, OpenAPI contract updates, and Inspector access-policy screens make external/guest write permissions visible and testable.
• Local MCP setups handle parallel dev and prod APIs more reliably. Profile-specific .dev-serve/local_http_port_dev and local_http_port_prod files, MCP config env wiring, and clearer /mcp session errors reduce stale-port and load-balanced-session failures.
• The docs site gains skills and use-case entry points. New skills catalog/detail pages, use-case data pages, SEO metadata, generated localized pages, and root-nav mirror updates make the public docs site cover more adoption paths.
• The bundled Inspector advances with the platform changes. The submodule now includes issue detail/list pages, access policy UI, admission-grant cells, and external actor attribution components.

What changed for npm package users

CLI (neotoma)

• Adds issue-oriented command coverage and supporting issue service operations for submit, sync, message, and status flows.
• Adds access-policy CLI/service coverage so operators can inspect and manage guest or external actor access rules.
• Updates MCP config generation so preset entries set NEOTOMA_MCP_LOCAL_HTTP_PORT_PROFILE for dev/prod slots when local port-file mode is enabled.
• Extends CLI base URL discovery to read profile-specific local HTTP port files before falling back to configured/default URLs.

Runtime / data layer

• Allows issue-submission external actor provenance through the /store request shape so GitHub-originated actors can be preserved without tripping unknown-field validation.
• Adds guest access token and access policy services/tests for controlling read/write behavior by entity type and external actor context.
• Returns clearer streamable HTTP MCP session errors: missing initialization remains 400, while an unknown/stale session id now reports a distinct 503 with load-balancer/restart guidance.

Shipped artifacts

• Updates openapi.yaml and generated src/shared/openapi_types.ts for issue/access/external actor contract changes.
• Updates npm-shipped docs, skills, hooks/plugin packages, MCP instructions, and generated site assets.
• Advances the inspector submodule pointer to the issue/access-policy UI commits.

API surface & contracts

• /store accepts top-level external_actor provenance for issue submission flows.
• OpenAPI types and unknown-field guard tests were regenerated/updated to keep runtime validation aligned with the declared contract.
• MCP local-port-file behavior is documented for signed shim and CLI/proxy discovery, including NEOTOMA_MCP_USE_LOCAL_PORT_FILE, NEOTOMA_MCP_LOCAL_HTTP_PORT_PROFILE, and NEOTOMA_MCP_PORT_PROBE_MS.

Behavior changes

• Legacy feedback cron/Netlify intake pieces are removed or replaced by issue-sync and GitHub-backed issue surfaces.
• Raw non-JSON fixture replay now permits source-only stores with no file_asset observation, matching the current unstructured-only store contract.
• Operators running both dev and prod local APIs can avoid port-file clobbering by selecting the matching local HTTP port profile.

Agent-facing instruction changes

• MCP instructions now describe profile-specific local HTTP port files for repo-local Cursor setups.
• Release/process instructions emphasize release-note completeness and test-build separation from formal release execution.
• Process-feedback skills are updated to the newer issue pipeline rather than the legacy feedback pipeline.

Plugin / hooks / SDK changes

• Updates shared hook/plugin messaging across Cursor, Codex, Claude Code, OpenCode, and the Claude Agent SDK adapter to match the issue/reporting workflow.
• Keeps generated hook docs and package README content aligned with the current agent workflow.

Security hardening

• Adds guest access policy documentation and tests for explicit entity-type access modes.
• Adds external actor attribution helpers and Inspector display components so GitHub-originated actors can be surfaced with provenance context.
• Improves MCP session diagnostics without exposing full session ids in logs.

Docs site & CI / tooling

• Adds skills pages, skill catalog data, skill markdown snippets, and generated localized skills pages.
• Adds use-case documentation and site data for agent auth, compliance, contracts, CRM, financial ops, healthcare, logistics, personal data, procurement, trading, and related verticals.
• Adds GitHub issue auto-label and upgrade-guidance workflow support.
• Updates root landing nav mirror tests and generated site pages to keep the Node-rendered landing page in sync with the frontend docs nav.

Internal changes

• Removes stale feedback-admin tests and Netlify functions that depended on deleted feedback modules.
• Updates issue operation mocks and CLI command coverage guard expectations for the new command surface.
• Updates setup tests for the new skills setup step.
• Tightens Inspector external actor badge typing in the submodule.

Fixes

• Fixes stale MCP HTTP session responses so clients can distinguish “never initialized” from “initialized against another/restarted instance.”
• Fixes site-copy lint issues in the new skills pages.
• Fixes source lint blockers in issue/access-policy tests and supporting services.
• Fixes release/test-build branch consistency by pushing the Inspector submodule branch before updating the superproject pointer.

Tests and validation

• Local pre-commit passed on the committed branch, including type check, ESLint, site-copy lint, default Vitest subset, and Playwright E2E.
• Targeted tests passed for issue operations, CLI command coverage, setup flow, root landing nav drift, and non-JSON fixture replay.
• Targeted test rerun passed for tests/cli/cli_init_commands.test.ts after one isolated concurrent/flaky failure during a hook run.
• GitHub Actions status on the draft PR: frontend passed; baseline and site_export are currently failing and need follow-up triage.

Breaking changes

No release-level breaking changes are declared for this test-build PR. Before converting this scope into a formal release, run the normal /release OpenAPI breaking-change diff and reconcile any validation tightening in the release supplement.

Test-build notes

• This PR is intentionally draft and exists to trigger CI as a test build.
• It does not create a GitHub Release, git tag, npm package, or sandbox deployment.
• docs/private remains untracked locally and intentionally excluded.
• Local uncommitted follow-up not yet included in this PR: scripts/run_neotoma_mcp_proxy.sh plus its short docs/developer/mcp/proxy.md note for unsigned proxy port-file support.