Command Help + Tier Visibility

Pick a plan tier to see exactly which commands and workflows are available for that tier.

This page is tier-aware for command visibility. Paid-only command rows are hidden until you select Pro, Team, or Enterprise.

Terminal First-Run (No Guessing)

Always run PG commands in the project root (the folder that contains pg.ps1).

PowerShell

Set-Location "C:\real\project\root" pg install backend --target "." # or: pg install frontend --target "." .\pg.ps1 start -Yes .\pg.ps1 map-structure .\pg.ps1 integration-init # existing/legacy repo only when missing .\pg.ps1 backend-start .\pg.ps1 frontend-start .\pg.ps1 status

CMD

cd /d "C:\real\project\root" pg install backend --target "." REM or: pg install frontend --target "." powershell -ExecutionPolicy Bypass -File ".\pg.ps1" start -Yes powershell -ExecutionPolicy Bypass -File ".\pg.ps1" map-structure powershell -ExecutionPolicy Bypass -File ".\pg.ps1" integration-init powershell -ExecutionPolicy Bypass -File ".\pg.ps1" backend-start powershell -ExecutionPolicy Bypass -File ".\pg.ps1" frontend-start powershell -ExecutionPolicy Bypass -File ".\pg.ps1" status

Start gate: legacy/half-built repos now block session start by default when map docs are missing or stale. Run .\pg.ps1 map-structure.

Integration ledger bootstrap: new PG installs now scaffold the shared frontend/backend integration files automatically. Older repos may need a one-time .\pg.ps1 integration-init if Memory-bank/frontend-integration.md does not exist yet.

Important: backend-start and frontend-start do not replace pg install or .\pg.ps1 start. They only claim roles inside an already bootstrapped project root.

Plan routing: the frontend/backend integration workflow and secure review workflow are paid workflow surfaces for Pro, Team, and Enterprise.

Warning-only override: .\pg.ps1 start -Yes -EnforcementMode warn

Narrate startup guard: the extension now detects the nearest AGENTS.md/pg.ps1 context, auto-runs startup once per context per UTC day, and reruns when you move into a new nested repo. Manual retry: Narrate: Run Startup For Current Context.

Tip: run .\pg.ps1 help to see the exact command set available in that project profile.

`.\pg.ps1 update` is profile-dependent. Use it only when `help` lists `update`.

Planning rule: when scope changes, add a REQ tag in Memory-bank/project-spec.md and map it to milestones in Memory-bank/project-details.md.

Command Catalog By Plan Tier

Includes VS Code, CLI, portal, and Slack command surfaces. The table is grouped into Extension commands, prompt handoff, frontend/backend integration, secure review workflow, governance, and enterprise controls.

Extension

Free keeps core Narrate commands and Narrate: Request Change Prompt. Pro unlocks extra prompt, export, report, and validation commands.

Frontend + Backend

integration-*, backend-start, and frontend-start are routed to Pro, Team, and Enterprise.

Secure Review

review-* is Pro+; Team shares the same workflow with collaborative operations, and Enterprise adds reviewer automation policy.

Team + Enterprise

Governance sync, Slack decision commands, seat controls, and enterprise-only policy-pack or reviewer automation controls stay in the paid governance tiers.

Command	What It Does	Surface	Tier

Paid Tier Deep Dive

Troubleshooting Quick Fixes

Common issues and exact fix direction.

Issue	Fix
Missing command in UI	Select a higher tier filter or check extension activation.
Wrong project root	Run commands in the folder that contains `pg.ps1`. In extension prompts, choose Open Fix Guide.
Export/report missing	These are Pro+ commands; verify plan in status bar and portal summary.
PG Push blocked	Run trust/dead-code fixes, then retry push with a compliant commit message.
Slack command timeout	Check backend health and tunnel status, then retry signed /pg command.
DB check runtime error	Confirm DATABASE_URL connectivity and DB reachability before self-check.
Missing frontend integration summary	Run `.\pg.ps1 integration-init` once in the project root. New installs scaffold it automatically; older repos may not have it yet.
`backend-start` or `frontend-start` feels like install/startup	They are role-claim commands only. First run `pg install ...` if needed, then `.\pg.ps1 start -Yes`, then the integration role command.

Plan + Feature Matrix

Open the full comparison page for complete free/trial/pro/team/enterprise ticks.

Open Pricing Matrix

What Narrate Is

Narrate is the VS Code product layer. It gives reading/toggle UX, quality gates, export/report tools, and guided policy checks. It helps developers and students understand code and ship safely.

Core Narrate Areas

Reading UX: Dev/Edu reading modes, exact/section view, split/full pane, source toggles.
Quality UX: Trust Score, Environment Doctor, Dead Code Scan, Commit Quality, PG Push gates.
Validation UX: API contract checks, codebase tour, cloud/observability checks.
Commercial UX: plan-aware command visibility and gated paid features.

Narrate: Local vs Server

Area	Where It Runs	Why
Status bar toggles, reading UI, local reports	Local extension runtime	Fast and works in local-first workflow.
Policy scoring, entitlement, governance authority	Server-side APIs	Central rule control and secure plan/policy enforcement.
AI narration provider calls	Local extension provider path	Optional. If no provider key, local fallback narration still works.

Narrate works without mandatory AI for core controls. AI is optional for richer narration output.

What PG Install + Memory-bank Do

pg install backend|frontend --target "." is a scaffold command. It creates workflow docs, scripts, hooks, and Memory-bank structure for that project root.

New/empty project: creates required governance/memory scaffolding, not your app business code.
Existing project: adds missing PG/Memory-bank files and keeps using your existing source tree.
Legacy/half-built project: run .\pg.ps1 map-structure after install/start to aggressively map current code tree + DB schema artifacts into Memory-bank docs.
Multiple projects: run install separately in each root (frontend and backend each keep independent state).

Frontend/Backend Integration Workflow

Shared ledger: the workflow writes to Memory-bank/frontend-integration.md, Memory-bank/frontend-integration/state.json, and page files under Memory-bank/frontend-integration/pages/.
New installs: current PG bootstrap scaffolds these files automatically.
Existing/legacy repos: if the ledger is missing, run .\pg.ps1 integration-init once after start/map-structure.
Role start: use .\pg.ps1 backend-start and .\pg.ps1 frontend-start only after the project root is already bootstrapped and the Memory-bank session is active.
Enforcement: guards require the integration summary/state/page artifacts and keep integration page files at <=500 lines.

Scaffold generation is script-driven (PowerShell/Python), not an AI call.

What Files `pg install` Adds (Core)

Path	Purpose
`pg.ps1`, `scripts/pg.ps1`, `pg.cmd`	Project command entrypoints (PowerShell/CMD).
`Memory-bank/project-spec.md`	Requirements/spec source of truth (REQ tags).
`Memory-bank/project-details.md`	Rolling milestone plan and session updates.
`Memory-bank/structure-and-db.md`	Architecture and data-layer summary.
`Memory-bank/tools-and-commands.md`	Runbook for runtime, shells, and command usage.
`Memory-bank/coding-security-standards.md`	Coding/security rules used by checks (applies to frontend and backend).
`Memory-bank/agentsGlobal-memory.md`	Append-only implementation memory log.
`Memory-bank/mastermind.md`	Decision/voting rationale ledger.
`.githooks/pre-commit`	Local guard for Memory-bank/session policy checks.
`scripts/generate_memory_bank.py`	Daily generation + retention cleanup entrypoint.

How Enforcement Works

Control	Mechanism	Outcome
Local memory workflow enforcement	`pg.ps1 start`, git hooks, local guard scripts	Forces session/docs/plan updates before clean commit flow.
Spec to milestone mapping	REQ tags in spec + milestone/session mapping checks	Scope changes must be tracked in project plan docs.
Plan-aware policy strictness	Server profile endpoint + entitlement/policy routes	Centralized control for paid-tier governance behavior.
Daily report retention	`generate_memory_bank.py --keep-days 7`	Keeps only configured latest daily files and prunes old ones.
Long log retention	`generate_memory_bank.py` archive rotation	Archives older sections from `agentsGlobal-memory.md` and `mastermind.md` when line limits are exceeded.

Recommended Commands

Set-Location "C:\real\project\root" pg install backend --target "." .\pg.ps1 help .\pg.ps1 start -Yes Narrate: Run Startup For Current Context .\pg.ps1 map-structure .\pg.ps1 integration-init # one-time for older repos when ledger is missing .\pg.ps1 backend-start .\pg.ps1 frontend-start .\pg.ps1 integration-summary .\pg.ps1 self-check -EnableDbIndexMaintenanceCheck .\pg.ps1 self-check -EnableDbIndexMaintenanceCheck -EnablePlaywrightSmokeCheck # for UI/frontend changes .\pg.ps1 status python scripts/generate_memory_bank.py --profile frontend --keep-days 7

Slack Voting + Decision Workflow

This flow is for Team/Enterprise governance. It is separate from normal chat.

Step	Command	Result
1. Create thread	`/pg thread Release gate :: approve\|needs-change\|reject`	Creates governance thread and option keys (for example: opt1, opt2, opt3).
2. Team vote	`/pg vote <THREAD_ID> opt1`	Records vote with auditable actor + timestamp.
3. Final decision	`/pg decide <THREAD_ID> approve opt1 final-go`	Finalizes decision (owner/manager role policy).
4. Pull to local	`.\pg.ps1 governance-worker -Once`	Applies pending decisions locally and acknowledges back to backend.

Slack Transport Prerequisites

SLACK_COMMANDS_ENABLED=true
SLACK_SIGNING_SECRET, SLACK_BOT_TOKEN, and (optional) SLACK_WEBHOOK_URL
SLACK_ALLOWED_TEAM_IDS and/or SLACK_ALLOWED_EMAILS for access control
Public callback URL reachable by Slack (tunnel/domain + correct signature age window)

Always-On Decision Sync

You have two ways to keep local state synced with Slack decisions:

From VS Code Extension

narrate.governance.autoSync.enabled = true narrate.governance.autoSync.intervalSeconds = 30 narrate.governance.autoSync.requireBackendMode = true

Runs while VS Code is open.

From CLI Worker

.\pg.ps1 governance-worker -PollSeconds 15 -ApproveCommand "& '.\scripts\governance_action_handler.ps1'"

Runs continuously while terminal process is alive.

Troubleshoot Fast

dispatch_failed / timeout: verify /health, tunnel status, and Slack signature setup.
invalid bearer token: rerun .\pg.ps1 governance-login.
No new governance events: not an error, means queue is currently empty.

Automation Model (What Runs Automatically)

Capability	Auto While VS Code Is Open	Manual/CI Trigger
Governance decision sync	Yes (if `narrate.governance.autoSync.enabled=true`)	`.\pg.ps1 governance-worker -Once`
Trust Score on save	Yes (if `narrate.trustScore.autoRefreshOnSave=true`)	`Narrate: Refresh Trust Score`
Post-write policy checks	Yes (if `narrate.enforcement.postWrite.enabled=true`)	`.\pg.ps1 self-check -WarnOnly -EnableDbIndexMaintenanceCheck`
Playwright smoke + release gates	Required for UI/frontend changes before final Memory-bank update	`.\pg.ps1 self-check -EnableDbIndexMaintenanceCheck -EnablePlaywrightSmokeCheck`
Final strict release check	Required before final Memory-bank update/commit	`.\pg.ps1 self-check -EnableDbIndexMaintenanceCheck`

Narrate does not silently auto-edit your app code in background loops. It runs checks and guidance; actions are explicit and auditable.

Guard rule: code commits are blocked unless latest strict self-check passed; UI-impacting changes must include Playwright smoke.

Cloud Score + Enterprise Value

MCP Cloud Score is metadata-only readiness scoring (dependency, coding standard, API contract, cloud controls). It does not upload source code bodies.

.\pg.ps1 mcp-cloud-score -WorkloadSensitivity regulated

.\pg.ps1 mcp-cloud-score -WorkloadSensitivity regulated -ControlCloudflareTunnel pass -ControlSecretsManager pass -ControlDbPortNotPublic pass

Why Enterprise Tier

Reviewer automation policy and enterprise escalation workflows.
Strict org-wide provider controls and governance domains.
Offline policy-pack lifecycle (issue/rotate) for high-control environments.
Expanded seat/governance operations with stronger audit posture.

Enterprise package APIs: GET /account/enterprise/offline-pack/info, POST /account/enterprise/offline-pack/activate, POST /pg-global-admin/board/enterprise/offline-pack/issue.

Release-to-Slack Recommended Sequence

.\pg.ps1 self-check -WarnOnly -EnableDbIndexMaintenanceCheck -EnablePlaywrightSmokeCheck

.\pg.ps1 closure-check -ClosureMode local-core -ApiBase "http://127.0.0.1:8787" -PublicBaseUrl "https://pg-ext.addresly.com"

.\pg.ps1 governance-digest -ApiBase "http://127.0.0.1:8787" -TeamKey "your-team"

AI Provider Setup (VS Code Settings)

Run Narrate: Open Model Settings for one-click jump, or open Settings and search narrate.model.

Setting Key	Purpose	Example
`narrate.model.baseUrl`	OpenAI-compatible endpoint.	`https://api.openai.com/v1` or `http://127.0.0.1:11434/v1`
`narrate.model.modelId`	Model name sent to provider.	`gpt-4o-mini`, `llama3.1`, `qwen2.5-coder`
`narrate.model.apiKey`	Provider API key if required.	`sk-...` (leave empty for local fallback narration path)
`narrate.model.timeoutMs`	Provider request timeout.	`25000`

For backend-side integration and governance flows, use server env in server/.env and keep secrets out of git.

Quick provider test: set model keys, then run Narrate: Toggle Reading Mode (Dev) on any code file; Ollama example base URL is http://127.0.0.1:11434/v1.

Handoff + Clipboard Behavior

Handoff commands generate prompts and copy them to clipboard. Some chat providers expose their own direct context actions, while others rely on manual paste.

Narrate: Request Change Prompt asks for your intent, then opens a markdown prompt + copies it.
Narrate: OpenAPI Fix Handoff Prompt builds API mismatch fix prompt + copies it.
Use Ctrl+V (or right-click Paste) in your target chat/editor.
From editor selection, use VS Code context menu: Add Selection to Chat.
If your provider extension shows actions like Add to ... or Explain with ..., those can push selection directly into that provider's chat input.

Why You Did Not See Auto-Paste

Direct chat insertion is provider-specific. Narrate keeps a provider-agnostic clipboard handoff path so the flow still works even when a provider does not expose direct insertion actions.