Module: Logi::Commands::Manual

Defined in:
lib/logi/commands/manual.rb

Overview

logi manual — agent-first self-loading manual.

One command that loads usage + the command catalog + RP-integration entry points into an AI agent's context (the onpod manual pattern): docs prompts can say "run logi manual" instead of pointing agents at multiple doc URLs. The embedded text is self-contained and offline-safe; --full additionally fetches the two runbook LLM splits from docs.

Constant Summary collapse

DOCS_BASE = 
"https://docs.1pass.dev"
RUNBOOKS = 
{
  "registration runbook" => "/llms/guide/cli-rp-registration.md",
  "integration runbook"  => "/llms/guide/agent-quickstart.md"
}.freeze
EMBEDDED =

Plain text on purpose — no colors/TTY layout. The primary reader is an AI agent ingesting stdout; humans get the same text fine.

<<~MANUAL
  # logi CLI — agent manual

  logi (1pass) is an OIDC Identity Provider. This manual is designed to be
  loaded into an AI agent's context via `logi manual`. It is self-contained
  for registering an RP (OAuth app) and starting a login integration.

  ## Key facts
  - Issuer / OAuth host: https://api.1pass.dev — the id_token `iss` is this
    literal. The console host start.1pass.dev is NOT an OAuth host
    (discovery/jwks return 404 there).
  - Discovery: https://api.1pass.dev/.well-known/openid-configuration
  - Valid scopes: openid profile:basic email  (bare `profile` is rejected)
  - redirect_uri matches byte-for-byte. `apps create` takes exactly one;
    add the rest (local / staging / prod / mobile scheme) with
    `apps add-redirect`.
  - client_secret / rp_health_secret are shown ONCE at create — put them in
    the deploy env, never in code/git. Missed them? Rotate in the developer
    console (https://start.1pass.dev) — CLI/API rotation is refused with
    403 use_web_portal because it requires web OTP step-up.
  - --client-type: confidential (backend can hide the secret) or public
    (mobile/SPA, PKCE-only, no client_secret). Immutable after create.

  ## Command catalog
    logi login                     Sign in (browser OAuth; --code for headless/SSH)
    logi whoami                    Show sign-in info
    logi developer register --email <e> --org "<o>"   Become a developer
    logi developer status          Check identity_verified_level
    logi developer verify-email    Enter the 6-digit email code (SSO signups skip this)
    logi apps create --name "<n>" --redirect-uri <url> \\
                     --scope openid profile:basic email --client-type <confidential|public>
    logi apps add-redirect <id> <uri>
    logi apps list | show <id> | verify <id> | delete <id>
    (secret rotation: developer console only — web OTP step-up required)
    logi token inspect <jwt>       Decode + verify a JWT against JWKS
    logi manual [--full]           This manual (--full appends both runbooks)

  ## RP registration flow (6 steps)
  1. logi login
  2. logi developer register --email <e> --org "<o>"
  3. logi developer status  →  if unverified: logi developer verify-email
  4. logi apps create ...   (client_id + secrets issued once)
  5. Inject env: LOGI_API_URL / LOGI_CLIENT_ID / LOGI_CLIENT_SECRET (confidential only) / LOGI_RP_HEALTH_SECRET
  6. logi apps verify <id>  (production domains go `pending` → admin review)

  ## Deep docs (fetch on demand)
  - Registration runbook: #{DOCS_BASE}/llms/guide/cli-rp-registration.md
  - Integration runbook (track branching + F1-F8 pitfalls):
    #{DOCS_BASE}/llms/guide/agent-quickstart.md
  - English editions: swap /llms/ for /llms-en/
  - Index of every topic: #{DOCS_BASE}/llms.txt

  Run `logi manual --full` to print both runbooks inline (network required).
MANUAL

Class Method Summary collapse

Class Method Details

.perform(full: false) ⇒ Object 



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/logi/commands/manual.rb', line 76

def self.perform(full: false)
  puts EMBEDDED
  return unless full

  RUNBOOKS.each do |label, path|
    body = fetch(path)
    if body
      puts "\n\n---\n# [#{label}] #{DOCS_BASE}#{path}\n\n"
      puts body
    else
      warn "⚠ Could not fetch #{label} (#{DOCS_BASE}#{path}) — network unavailable? " \
           "Fetch it yourself with: curl #{DOCS_BASE}#{path}"
    end
  end
end