PG PG Memory Bank Help

Command Help + Tier Visibility

Every command and workflow below is free. Search the catalog, or jump to a workflow.

Terminal First-Run (No Guessing)

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

One-time machine setup from an updated PG repo root: pwsh -ExecutionPolicy Bypass -File ./scripts/sync_global_pg_cli.ps1

PowerShell

Set-Location "C:\real\project\root" pg install backend --target "." # or: install frontend --target "." pg start -Yes pg map-structure pg tapsign -Action catalog pg tapsign -Action plan -Profile universal-web -Endpoint POST:/login pg integration-init # existing/legacy repo only when missing pg backend-start pg frontend-start pg status

macOS / Linux Shell

cd "/real/project/root" pg install backend --target "." # or: install frontend --target "." pg start -Yes pg map-structure pg tapsign -Action catalog pg tapsign -Action plan -Profile universal-web -Endpoint POST:/login pg integration-init # existing/legacy repo only when missing pg backend-start pg frontend-start pg status

CMD

cd /d "C:\real\project\root" pg install backend --target "." REM or: install frontend --target "." pg start -Yes pg map-structure pg tapsign -Action catalog pg tapsign -Action plan -Profile universal-web -Endpoint POST:/login pg integration-init pg backend-start pg frontend-start pg status

Shell translation: After the one-time sync, use pg install ..., pg start ..., pg map-structure, and pg status as the primary commands. If pg is still not found, fall back to the explicit $HOME/.pg-cli path. Repo-local forms such as .\pg.ps1 ..., pwsh -ExecutionPolicy Bypass -File ./pg.ps1 ..., and pg.cmd ... still work.

Start gate: legacy/half-built repos now block session start by default when map docs are missing or stale. Run pg 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 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 start. They only claim roles inside an already bootstrapped project root.

Warning-only override: pg 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.

User-editable agent instructions: the only intended user-editable instruction file is .github/instructions/user-custom.instructions.md inside the project root. pg start includes it in the required read list when present. Keep it plain text/markdown only: no executable command blocks, no secrets, and no instructions to bypass safeguards or ignore higher-priority rules.

Tip: run .\pg.ps1 help to see the full project-local command set. The short pg launcher now forwards repo-local commands too.

pg update / .\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

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

CLI shell note: the catalog keeps PowerShell-style command names for the repo-local PG script. On macOS/Linux shells, run the same command through pwsh -ExecutionPolicy Bypass -File ./pg.ps1 ...; on Windows CMD use pg.cmd ....

Extension

Core Narrate commands, Narrate: Request Change Prompt, and the prompt, export, report and validation commands.

Frontend + Backend

integration-*, backend-start and frontend-start run the frontend and backend integration workflow.

TapSign

tapsign plans web, WordPress, Shopify, mobile, Guardian, SSO and provider-proxy protection from the synced policy doc.

Secure Review

review-* runs the builder and reviewer workflow, with shared operations for teams and reviewer automation policy.

Teams

Governance sync, Slack decision commands, policy packs and reviewer automation controls.

Command What It Does Surface Tier

Workflow deep dive

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, and the student-first Instant Translate line explainer.
  • Quality UX: Trust Score, Environment Doctor, Dead Code Scan, Commit Quality, PG Push gates.
  • Validation UX: API contract checks, codebase tour, cloud/observability checks.

Instant Translate: What You See

Use this when you want the extension to explain one line at a time in simpler student language.

  • Turn it on: use the visible Narrate Reading picker or run Narrate: Toggle Instant Translate.
  • Look in Narrate Help: the Instant Translate card stays at the top, and when you scroll down you still keep Command Help, Toggle Panel, and Trust Score underneath.
  • Click any line: select a source-code line or an exact-reading line and the real code line is shown in the Instant Translate card.
  • Read it in place: the same selection also gets a compact explainer directly under the chosen line in the editor.
  • Student-first output: the explanation always uses Education + Full Beginner, so brackets, imports, constants, and syntax cues are broken down more plainly.

Narrate: Local vs Server

AreaWhere It RunsWhy
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 with neutral starter docs, 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 map-structure after install/start to aggressively map current code tree + DB schema artifacts into Memory-bank docs.
  • Project-independence rule: install should not copy another repository's product details into this project.
  • Multiple projects: run install separately in each root (frontend and backend each keep independent state).
  • User-editable overlay file: add personal or team style rules to .github/instructions/user-custom.instructions.md instead of editing repo-owned instruction files.

Exact folder: open .github, then instructions, then edit user-custom.instructions.md. That is the only intended user-editable agent-instruction file in the repo.

Read + enforcement: pg start includes that file in the required read list when present, and the guard treats it as a safe text-only overlay. It cannot override AGENTS, higher-priority safety instructions, or repo enforcement.

Safety boundary: keep it to plain text/markdown guidance such as naming, structure, testing, and workflow preferences. Do not put shell/code blocks, secrets, or instructions to bypass checks, expose credentials, or ignore safeguards in that file.

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 integration-init once after start/map-structure.
  • Role start: use pg backend-start and pg 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)

PathPurpose
pg.ps1, scripts/pg.ps1, pg.cmdProject command entrypoints (PowerShell/CMD).
.github/copilot-instructions.mdProject-local Copilot instruction base generated for the installed repo.
.github/instructions/user-custom.instructions.mdIntended user-editable overlay file for project-specific style and workflow preferences.
Memory-bank/project-spec.mdProject-local requirements/spec starter that should be replaced with this repo's real scope.
Memory-bank/project-details.mdProject-local rolling plan and session log starter.
Memory-bank/structure-and-db.mdProject-local architecture/data starter that legacy repos refine through map-structure.
Memory-bank/tools-and-commands.mdRunbook for runtime, shells, and command usage in this repo.
Memory-bank/coding-security-standards.mdCoding/security rules used by checks (applies to frontend and backend).
Memory-bank/agentsGlobal-memory.mdAppend-only implementation memory log.
Memory-bank/mastermind.mdDecision/voting rationale ledger.
.githooks/pre-commitLocal guard for Memory-bank/session policy checks.
scripts/generate_memory_bank.pyDaily generation + retention cleanup entrypoint.

All of these paths are relative to the installed project root. Example: /path/to/project/Memory-bank/mastermind.md, /path/to/project/Memory-bank/agentsGlobal-memory.md, and /path/to/project/.github/instructions/user-custom.instructions.md.

How Enforcement Works

ControlMechanismOutcome
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 Central control for governance behaviour.
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 help pg start -Yes cd "/real/project/root" pg help pg start -Yes Narrate: Run Startup For Current Context pg map-structure pg integration-init # one-time for older repos when ledger is missing pg 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.

StepCommandResult
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

  • zsh/bash says permission denied for ./pg.ps1: run pwsh -ExecutionPolicy Bypass -File ./pg.ps1 ... instead, or open a pwsh terminal first.
  • 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)

CapabilityAuto While VS Code Is OpenManual/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

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

Release-to-Slack Recommended Sequence

.\pg.ps1 self-check -WarnOnly -EnableDbIndexMaintenanceCheck -EnablePlaywrightSmokeCheck .\pg.ps1 governance-digest -ApiBase "https://your-governance-server" -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 KeyPurposeExample
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.