logi-cli 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e169d7a77d8a0d247460b3010da3abcc4925c47a579582d24efcc90839f8466e
-  data.tar.gz: 6ad06a8bd52b41c8b5ebb5d12262edd848d4355519ed573bf47a15c22e9278ce
+  metadata.gz: fa3a61b59de983a4b5b5873e91456a8906ed221afb614665d5021a92524d13dd
+  data.tar.gz: d247641e4e0144646af75dff18f92fd57104c06088a646dc1b2965c20f70f73e
 SHA512:
-  metadata.gz: 80c5570bc590c7224a8049aeecd116264de4b916e2e2a42af5ffe9b46f1cfbe089256c121f575a44d0ea99acda20ea00aa23ef3cdbb57e3a4e009d3b662a13b3
-  data.tar.gz: 6d252d9bc5884d0da4c195423017e36689227200c312d0dd240cffed2478a87d3c02fbde246be8da849309a2ac0d6aae418384fb95767f19c2474c4be37d58a6
+  metadata.gz: 88f30a07076fd1869f156f2397c5027cd2caaaac28a923922d13a05352de8692c88413d13099b42ed2f1152e5338419470d4e4211b3cab8bc820f3a3609fdce2
+  data.tar.gz: f0cfc31661ecc9cbf9969371bf26afec6d6ac06a9bec17d6753d72dab4a1d397e5993186a6314a96eb4a65318d1ebaf76f9b29901232caa6301a0f2ceb4c8f1b

data/CHANGELOG.md

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-06
+
+### Added
+- `logi manual` — agent-oriented self-loading manual (the onpod `manual` pattern): key OAuth facts, full command catalog, and the 6-step RP registration flow in one offline-safe dump. `--full` additionally fetches the registration + integration runbook LLM splits from docs.1pass.dev.
+
 ## [0.1.0] - 2026-05-27
 
 Initial public release on RubyGems.org.

data/lib/logi/cli.rb

@@ -23,6 +23,7 @@ module Logi
         puts "  logi apps verify <id> -r URL                 # Check an RP integration (env / redirect URI)"
         puts "  logi apps rotate-secret <id>                  # Rotate client_secret"
         puts "  logi whoami                                   # Show sign-in info"
+        puts "  logi manual                                   # Agent-oriented manual (paste into your AI agent)"
         puts "  logi --help                                   # All commands"
       else
         puts pastel.yellow("You're not signed in yet.")
@@ -49,21 +50,33 @@ module Logi
     method_option :api_url,    type: :string,  default: nil,   desc: "logi API URL (default: https://api.1pass.dev)"
     method_option :portal_url, type: :string,  default: nil,   desc: "Developer Portal URL (default: https://start.1pass.dev)"
     method_option :name,       type: :string,  default: "CLI", desc: "PAK name"
-    method_option :scope,      type: :array,   default: nil,   desc: "Scopes to request"
-    method_option :code,       type: :boolean, default: false, desc: "Sign in with a code instead of a browser (for SSH / headless environments)"
+    method_option :scope,      type: :array,   default: nil,   desc: "Scopes to request (clamped to the allowlist)"
+    method_option :code,       type: :boolean, default: false, desc: "Headless: print a code instead of opening a browser (for SSH / no-GUI)"
+    method_option :loopback,   type: :boolean, default: false, desc: "Use the loopback redirect flow (no code; same-device only)"
     def login
       api_url    = options[:api_url] || ENV["LOGI_API_URL"] || Config::DEFAULT_API_URL
       portal_url = options[:portal_url] || ENV["LOGI_PORTAL_URL"]
 
-      if options[:code]
-        Commands::DeviceLogin.perform(api_url: api_url, portal_url: portal_url)
-      else
+      if options[:loopback]
+        # Same-device loopback redirect (PKCE). No code to type; auto-completes
+        # via 127.0.0.1 callback. Supports custom --scope.
         Commands::Login.perform(
           api_url:    api_url,
           portal_url: portal_url,
           name:       options[:name],
           scopes:     options[:scope]
         )
+      else
+        # Default: device flow. Opens the browser with the code pre-filled AND
+        # prints the code, so the user can approve here or on another device.
+        # `--code` skips the browser for headless / SSH environments.
+        Commands::DeviceLogin.perform(
+          api_url:      api_url,
+          portal_url:   portal_url,
+          name:         options[:name],
+          scopes:       options[:scope],
+          open_browser: !options[:code]
+        )
       end
     end
 
@@ -94,9 +107,19 @@ module Logi
     desc "app SUBCOMMAND", "(alias) same as `apps`", hide: true
     subcommand "app", Commands::App
 
+    desc "developer SUBCOMMAND", "Developer onboarding (register / status / verify-email)"
+    subcommand "developer", Commands::Developer
+
     desc "token SUBCOMMAND", "JWT access token tools (inspect)"
     subcommand "token", Commands::Token
 
+    desc "manual", "Print the agent-oriented manual (self-contained; --full appends the online runbooks)"
+    method_option :full, type: :boolean, default: false,
+                  desc: "Also fetch and print the registration + integration runbooks (network required)"
+    def manual
+      Commands::Manual.perform(full: options[:full])
+    end
+
     def self.exit_on_failure?
       true
     end

data/lib/logi/commands/app.rb

@@ -46,25 +46,37 @@ module Logi
       method_option :scope, type: :array, default: [], aliases: "-s",
                     desc: "Scopes to enable (e.g. -s openid profile:basic email). Optional."
       method_option :webhook_url, type: :string
+      method_option :backchannel_logout_uri, type: :string,
+                    desc: "OIDC back-channel logout endpoint on your RP"
+      method_option :health_url, type: :string,
+                    desc: "RP health endpoint logi pings hourly (must be public, no private IPs)"
+      method_option :health_check, type: :boolean, default: true,
+                    desc: "Enable hourly RP health checks. Use --no-health-check to disable."
+      method_option :client_type, type: :string,
+                    desc: "confidential (default) or public"
       def create
         data = authed_client.post("/api/v1/applications", body: {
           application: {
             name: options[:name],
             redirect_uris: [ options[:redirect_uri] ],
-            allowed_scopes: options[:scope],
-            webhook_url: options[:webhook_url]
+            # Flatten whitespace inside each --scope arg so BOTH `--scope openid profile email`
+            # and `--scope "openid profile email"` (Thor passes the quoted form as one element)
+            # resolve to separate scope names. Avoids a single bogus "openid profile email" scope.
+            allowed_scopes: Array(options[:scope]).flat_map { |s| s.to_s.split(/\s+/) }.reject(&:empty?),
+            webhook_url: options[:webhook_url],
+            backchannel_logout_uri: options[:backchannel_logout_uri],
+            health_url: options[:health_url],
+            # Only send health_check_enabled when explicitly opted out, so the
+            # server default (enabled) applies otherwise.
+            health_check_enabled: (options[:health_check] == false ? false : nil),
+            client_type: options[:client_type]
           }.compact
         })
         Output.success(data, options) do
-          puts pastel.green("✓ App created")
-          puts "  client_id:     #{data['client_id']}"
-          puts "  client_secret: #{pastel.yellow(data['client_secret'])}"
-          puts pastel.dim("  ⚠ The secret is only shown once. Store it somewhere safe.")
+          print_create_result(data)
         end
       rescue HttpClient::Error => e
-        Output.failure(code: "create_failed", message: e.body.to_s, status: e.status, options: options) do
-          abort pastel.red("Couldn't create app: #{e.status} #{e.body}")
-        end
+        handle_create_error(e)
       end
 
       desc "rotate-secret ID", "Rotate the client_secret"
@@ -127,10 +139,23 @@ module Logi
 
         # Check 2: tier
         tier = app["tier"]
-        if tier == "production"
+        case tier
+        when "production"
           ok "Tier: production"
+        when nil
+          warn "Tier: unknown (server didn't report a tier)."
         else
-          warn "Tier: sandbox — only localhost / staging redirects are allowed. To use a production URL, request a tier upgrade."
+          warn "Tier: #{tier} — only localhost / staging redirects are allowed. To use a production URL, request a tier upgrade."
+        end
+
+        # Health-check status (only shown when the server reports it).
+        unless app["health_check_enabled"].nil?
+          if app["health_check_enabled"]
+            status = app["rp_health_status"] || "unknown"
+            ok "Health checks: enabled (status: #{status})"
+          else
+            warn "Health checks: disabled"
+          end
         end
 
         # Check 3: redirect_uri registration
@@ -162,7 +187,8 @@ module Logi
         api_url = Config.load.api_url
         puts "  LOGI_API_URL=#{api_url}"
         puts "  LOGI_CLIENT_ID=#{app['client_id']}"
-        puts "  LOGI_CLIENT_SECRET=" + pastel.dim("(issued via rotate-secret)")
+        puts "  LOGI_CLIENT_SECRET=" + pastel.dim("(shown once at create — or rotate-secret to re-issue)")
+        puts "  LOGI_RP_HEALTH_SECRET=" + pastel.dim("(shown once at create)")
         puts ""
         puts pastel.dim("Docs: https://docs.1pass.dev/guide/troubleshooting")
       rescue HttpClient::Error => e
@@ -219,16 +245,67 @@ module Logi
             client_id: app["client_id"],
             tier: app["tier"],
             status: app["status"],
+            health_check_enabled: app["health_check_enabled"],
+            rp_health_status: app["rp_health_status"],
             redirect_uris: app["redirect_uris"],
             target_redirect_uri: target_uri,
             checks: checks,
             recommended_env: {
-              "LOGI_API_URL"      => Config.load.api_url,
-              "LOGI_CLIENT_ID"    => app["client_id"],
-              "LOGI_CLIENT_SECRET" => "(rotate-secret to issue)"
+              "LOGI_API_URL"        => Config.load.api_url,
+              "LOGI_CLIENT_ID"      => app["client_id"],
+              "LOGI_CLIENT_SECRET"  => "(shown once at create / rotate-secret)",
+              "LOGI_RP_HEALTH_SECRET" => "(shown once at create)"
             }
           }
         end
+
+        # Human-mode output for `apps create`: identifiers + the one-time
+        # secrets + a ready-to-paste env block. Secrets are NEVER written to a
+        # file by the CLI; the user copies them from the terminal.
+        def print_create_result(data)
+          puts pastel.green("✓ App created")
+          puts "  client_id:     #{data['client_id']}"
+          puts "  status:        #{data['status']}" if data["status"]
+          puts ""
+          if data["client_secret"]
+            puts "  client_secret:     #{pastel.yellow(data['client_secret'])}"
+          else
+            puts pastel.dim("  client_secret:     (none — public client)")
+          end
+          if data["rp_health_secret"]
+            puts "  rp_health_secret:  #{pastel.yellow(data['rp_health_secret'])}"
+          end
+          puts ""
+          puts pastel.bold("Paste these into your RP's environment:")
+          puts pastel.dim("# secrets below are shown ONCE — store them now")
+          puts "LOGI_API_URL=#{Config.load.api_url}"
+          puts "LOGI_CLIENT_ID=#{data['client_id']}"
+          puts "LOGI_CLIENT_SECRET=#{data['client_secret']}" if data["client_secret"]
+          puts "LOGI_RP_HEALTH_SECRET=#{data['rp_health_secret']}" if data["rp_health_secret"]
+          puts ""
+          puts pastel.dim("  ⚠ The client_secret and rp_health_secret are only shown once. Store them somewhere safe.")
+        end
+
+        def handle_create_error(e)
+          code = e.body.is_a?(Hash) ? e.body["error"] : nil
+          error_code, message =
+            case code
+            when "identity_verification_required"
+              [ "identity_verification_required",
+                "Your email must be verified before registering an RP. Run: logi developer verify-email" ]
+            when "forbidden"
+              [ "forbidden",
+                "You need a developer or admin role first. Run: logi developer register" ]
+            else
+              [ "create_failed", "Couldn't create app: #{e.status} #{e.body}" ]
+            end
+          # Emit the actionable hint in BOTH human and --json modes, and always
+          # exit non-zero so automation never reads a 403 as success.
+          Output.failure(code: error_code, message: message, status: e.status, options: options) do
+            abort pastel.red(message.sub(". Run: ", "\n       → "))
+          end
+          exit 1
+        end
       end
     end
   end

data/lib/logi/commands/developer.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Logi
+  module Commands
+    # Developer self-serve: promote your account to a developer, check its
+    # identity-verification state, and verify your email with a code.
+    #
+    # Why: registering an RP (`logi apps create`) requires (1) a developer/admin
+    # role and (2) an identity-verified email. These commands let an AI agent or
+    # a human complete the whole onboarding from the terminal, no web console.
+    #
+    # All endpoints authenticate with the PAK (Bearer) — no special scope is
+    # required (same trust level as `promote_to_developer`).
+    class Developer < Thor
+      class_option :json, type: :boolean, default: false,
+                   desc: "JSON output mode for LLM and CI workflows. You can also set LOGI_OUTPUT=json."
+
+      desc "register", "Promote your account to a developer (creates a personal org)"
+      method_option :email, type: :string,
+                    desc: "Email to attach (required if your account has no email yet)"
+      method_option :org, type: :string,
+                    desc: "Name for your personal organization"
+      def register
+        body = {
+          email_address: options[:email],
+          organization_name: options[:org]
+        }.compact
+
+        data = authed_client.post("/api/v1/me/promote_to_developer", body: body)
+        user = data["user"] || {}
+        org  = data["organization"] || {}
+
+        Output.success(data, options) do
+          puts pastel.green("✓ You're a developer now")
+          puts "  role:         #{user['role']}"
+          puts "  email:        #{user['email_address'] || '-'}"
+          puts "  organization: #{org['name'] || '-'}#{org['slug'] ? " (#{org['slug']})" : ''}"
+          puts ""
+          unless identity_verified?(user)
+            puts pastel.yellow("  Your email isn't verified yet — RP registration needs it.")
+            puts pastel.dim("    → logi developer verify-email")
+          end
+        end
+      rescue HttpClient::Error => e
+        handle_register_error(e)
+      end
+
+      desc "status", "Show your developer role and identity-verification state"
+      def status
+        data = authed_client.get("/api/v1/me")
+        user = data["user"] || {}
+
+        Output.success({ user: user }, options) do
+          puts pastel.bold("logi developer status")
+          puts ""
+          puts "  role:                    #{user['role'] || '-'}"
+          puts "  identity_verified_level: #{user['identity_verified_level'] || '-'}"
+          puts "  email:                   #{user['email_address'] || '-'}"
+          puts ""
+          if identity_verified?(user)
+            ok "Identity verified — you can register RPs."
+          else
+            warn "Identity not verified — required before `logi apps create`."
+            puts pastel.dim("    → logi developer verify-email")
+          end
+        end
+      rescue HttpClient::Error => e
+        Output.failure(code: "status_failed", message: "Couldn't fetch status: #{e.status} #{e.body}",
+                       status: e.status, options: options) do
+          abort pastel.red("Couldn't fetch status: #{e.status} #{e.body}")
+        end
+        exit 1
+      end
+
+      desc "verify-email", "Verify your email by entering a 6-digit code sent to your inbox"
+      def verify_email
+        client = authed_client
+
+        # Short-circuit: already verified → no email is sent.
+        me = client.get("/api/v1/me")["user"] || {}
+        if identity_verified?(me)
+          Output.success({ identity_verified_level: me["identity_verified_level"] }, options) do
+            puts pastel.green("✓ Your email is already verified.")
+          end
+          return
+        end
+
+        # In JSON / non-interactive mode the code comes from LOGI_VERIFY_CODE.
+        # Validate it BEFORE sending an email so an automation mistake doesn't
+        # trigger a wasted email + an out-of-contract abort.
+        preflight_code = noninteractive_code
+        if Output.json?(options) && (preflight_code.nil? || preflight_code.empty?)
+          Output.failure(
+            code: "code_required",
+            message: "Set LOGI_VERIFY_CODE with the 6-digit code in JSON mode.",
+            options: options
+          ) { abort pastel.red("Set LOGI_VERIFY_CODE with the 6-digit code in JSON mode.") }
+          exit 1
+        end
+
+        client.post("/api/v1/me/email_verifications")
+        Output.chatter(pastel.dim("A 6-digit code was sent to your email (valid 10 minutes)."), options)
+
+        code = preflight_code && !preflight_code.empty? ? preflight_code : read_code
+        data = client.post("/api/v1/me/email_verifications/verify_code", body: { code: code })
+
+        Output.success(data, options) do
+          puts pastel.green("✓ Email verified")
+          puts "  identity_verified_level: #{data['identity_verified_level']}"
+        end
+      rescue HttpClient::Error => e
+        handle_verify_error(e)
+      end
+
+      no_commands do
+        def pastel
+          @pastel ||= Pastel.new
+        end
+
+        def authed_client
+          config = Config.load
+          unless config.authenticated?
+            abort pastel.red("You need to sign in. Run `logi login`.")
+          end
+          HttpClient.new(base_url: config.api_url, api_key: config.api_key)
+        end
+
+        def identity_verified?(user)
+          level = user["identity_verified_level"]
+          !level.nil? && level != "unverified"
+        end
+
+        # The code from LOGI_VERIFY_CODE (CI / agent path), or nil if unset.
+        def noninteractive_code
+          env_code = ENV["LOGI_VERIFY_CODE"]
+          env_code.nil? ? nil : env_code.strip
+        end
+
+        # Interactively prompt for the 6-digit code (human mode only — JSON mode
+        # is short-circuited to LOGI_VERIFY_CODE before this is reached).
+        def read_code
+          TTY::Prompt.new.ask("Enter the 6-digit code:") do |q|
+            q.required true
+            q.validate(/\A\d{6}\z/, "Enter exactly 6 digits.")
+          end
+        end
+
+        def ok(msg);   puts pastel.green("  ✓ ") + msg; end
+        def warn(msg); puts pastel.yellow("  ⚠ ") + msg; end
+
+        def handle_register_error(e)
+          code = e.body.is_a?(Hash) ? e.body["error"] : nil
+          error_code, message =
+            case code
+            when "email_required"
+              [ "email_required", "An email is required. Pass --email you@example.com." ]
+            when "invalid_email"
+              [ "invalid_email", "That email looks invalid." ]
+            when "email_taken"
+              [ "email_taken", "That email is already in use." ]
+            else
+              [ "register_failed", "Couldn't register as a developer: #{e.status} #{e.body}" ]
+            end
+          Output.failure(code: error_code, message: message, status: e.status, options: options) do
+            abort pastel.red(message)
+          end
+          exit 1
+        end
+
+        def handle_verify_error(e)
+          code = e.body.is_a?(Hash) ? e.body["error"] : nil
+          error_code, message =
+            case code
+            when "no_deliverable_email"
+              [ "no_deliverable_email",
+                "No deliverable email on your account. Add a real email first: logi developer register --email you@example.com" ]
+            when "rate_limited"
+              [ "rate_limited", "A code was just sent — wait a moment before requesting another." ]
+            when "invalid_or_expired"
+              [ "invalid_or_expired",
+                "That code is invalid or expired. Run `logi developer verify-email` again for a new one." ]
+            when "too_many_attempts"
+              [ "too_many_attempts", "Too many attempts. Request a fresh code with `logi developer verify-email`." ]
+            else
+              [ "verify_email_failed", "Couldn't verify your email: #{e.status} #{e.body}" ]
+            end
+          Output.failure(code: error_code, message: message, status: e.status, options: options) do
+            abort pastel.red(message)
+          end
+          exit 1
+        end
+      end
+    end
+  end
+end

data/lib/logi/commands/device_login.rb

@@ -1,16 +1,23 @@
 # frozen_string_literal: true
 
+require "cgi"
 require "json"
 require "net/http"
 require "uri"
 
 module Logi
   module Commands
-    # Device-code login for headless / SSH environments.
+    # Device-code login — the default `logi login` flow.
+    #
+    # Unifies "approve in browser" and "enter a code" in one flow (like gh):
+    # by default we open the browser to verification_uri_complete (the code is
+    # pre-filled) AND print the code, so the user can approve on this device or
+    # type the code on another device / over SSH. `open_browser: false`
+    # (`logi login --code`) skips the browser for headless environments.
     #
     # Flow:
-    #   1. POST /cli/auth/device → receive user_code + device_code + verification_uri
-    #   2. Show the user_code and URL to the developer
+    #   1. POST /cli/auth/device → receive user_code + device_code + verification_uri(_complete)
+    #   2. Open the browser (code pre-filled) and/or print the code + URL
     #   3. Poll POST /cli/auth/device/poll every `interval` seconds
     #   4. On success receive PAK → save credentials
     module DeviceLogin
@@ -18,29 +25,48 @@ module Logi
 
       POLL_TIMEOUT = 600  # 10 minutes max
 
-      def perform(api_url:, portal_url: nil, **)
-        pastel  = Pastel.new
-        portal  = portal_url || ENV["LOGI_PORTAL_URL"] || Login::DEFAULT_PORTAL
+      def perform(api_url:, portal_url: nil, scopes: nil, name: "CLI", open_browser: true, **)
+        pastel          = Pastel.new
+        portal_override = portal_url || ENV["LOGI_PORTAL_URL"]
+        portal          = portal_override || Login::DEFAULT_PORTAL
 
         # Step 1: issue device code
-        grant = request_device_code(api_url: api_url)
+        grant = request_device_code(api_url: api_url, scopes: scopes)
         if grant.nil?
           abort pastel.red("Couldn't get a device code. Check your connection to the server.")
         end
 
         user_code        = grant["user_code"]
         device_code      = grant["device_code"]
-        verification_uri = grant["verification_uri"] || "#{portal}/cli/activate"
+        if portal_override
+          # Local / self-hosted: ignore the server-supplied (prod) URI and build
+          # the URL against the configured portal, so the browser opens the same
+          # server that minted this code instead of start.1pass.dev.
+          verification_uri          = "#{portal}/cli/activate"
+          verification_uri_complete = "#{verification_uri}?user_code=#{CGI.escape(user_code.to_s)}"
+        else
+          verification_uri = grant["verification_uri"] || "#{portal}/cli/activate"
+          # Code pre-filled URL — fall back to building it if the server is older.
+          verification_uri_complete =
+            grant["verification_uri_complete"].to_s.empty? ?
+              "#{verification_uri}?user_code=#{CGI.escape(user_code.to_s)}" :
+              grant["verification_uri_complete"]
+        end
         interval         = (grant["interval"] || 5).to_i
         expires_in       = (grant["expires_in"] || 600).to_i
 
-        # Step 2: display to user
+        # Step 2: present both paths — approve in browser OR enter the code.
         puts ""
-        puts pastel.bold("Open the URL below in your browser and enter the code.")
+        puts pastel.bold("Sign in: approve in your browser, or enter the code on another device.")
         puts ""
-        puts "  URL:   " + pastel.cyan(verification_uri)
         puts "  Code:  " + pastel.bold.yellow(user_code)
+        puts "  URL:   " + pastel.cyan(verification_uri)
         puts ""
+        if open_browser
+          puts pastel.dim("Opening your browser… (the code is pre-filled — just approve)")
+          Login.open_browser(verification_uri_complete)
+          puts ""
+        end
         puts pastel.dim("Waiting for approval… (expires in #{expires_in / 60} minutes)")
         puts ""
 
@@ -61,7 +87,7 @@ module Logi
           case error
           when nil
             # Success — result contains token
-            save_and_print(result, pastel)
+            save_and_print(result, pastel, name: name)
             return result
           when "authorization_pending"
             next
@@ -78,13 +104,14 @@ module Logi
         end
       end
 
-      def request_device_code(api_url:)
+      def request_device_code(api_url:, scopes: nil)
         uri = URI.join(api_url, "/cli/auth/device")
         req = Net::HTTP::Post.new(uri.path,
           "Content-Type" => "application/json",
           "Accept"       => "application/json"
         )
-        req.body = "{}"
+        body = scopes ? { scope: Array(scopes).join(" ") } : {}
+        req.body = JSON.generate(body)
         res = http(uri).request(req)
         JSON.parse(res.body)
       rescue => e
@@ -105,11 +132,11 @@ module Logi
         nil
       end
 
-      def save_and_print(token_response, pastel)
+      def save_and_print(token_response, pastel, name: "CLI")
         Config.save(
           api_key: token_response["token"],
           api_url: token_response["api_url"] || Login::DEFAULT_API,
-          name:    "CLI (device)"
+          name:    name
         )
 
         user = token_response["user"] || {}

data/lib/logi/commands/manual.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Logi
+  module Commands
+    # `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.
+    module Manual
+      DOCS_BASE = "https://docs.1pass.dev"
+      RUNBOOKS = {
+        "registration runbook" => "/llms/guide/cli-rp-registration.md",
+        "integration runbook"  => "/llms/guide/agent-quickstart.md"
+      }.freeze
+
+      # Plain text on purpose — no colors/TTY layout. The primary reader is
+      # an AI agent ingesting stdout; humans get the same text fine.
+      EMBEDDED = <<~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
+
+      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
+
+      def self.fetch(path)
+        uri = URI("#{DOCS_BASE}#{path}")
+        res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 5, read_timeout: 10) do |http|
+          http.get(uri.path)
+        end
+        res.is_a?(Net::HTTPSuccess) ? res.body : nil
+      rescue StandardError
+        nil
+      end
+      private_class_method :fetch
+    end
+  end
+end

data/lib/logi/config.rb

@@ -4,7 +4,11 @@ module Logi
   # Load/save credentials.json. Default path: ~/.config/logi/credentials.json
   # Environment variables LOGI_API_KEY / LOGI_API_URL take precedence when set.
   class Config
-    DEFAULT_API_URL = "http://localhost:3000"
+    # Production default. The shipped gem must point at prod out of the box —
+    # otherwise `logi login` issues the authorize request to start.1pass.dev
+    # but POSTs the token exchange to localhost, which 404s for every user.
+    # Local development overrides this with LOGI_API_URL=http://localhost:3000.
+    DEFAULT_API_URL = "https://api.1pass.dev"
 
     def self.path
       File.expand_path(ENV.fetch("LOGI_CONFIG_PATH", "~/.config/logi/credentials.json"))

data/lib/logi/http_client.rb

@@ -67,6 +67,8 @@ module Logi
         req.body = JSON.dump(body)
       end
       req["Accept"] = "application/json"
+      # Identify the CLI so the server records created_via=cli (not "api").
+      req["X-Logi-Client-Type"] = "cli"
       req
     end
 

data/lib/logi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Logi
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/logi.rb

@@ -19,5 +19,7 @@ require_relative "logi/output"
 require_relative "logi/commands/login"
 require_relative "logi/commands/device_login"
 require_relative "logi/commands/app"
+require_relative "logi/commands/developer"
 require_relative "logi/commands/token"
+require_relative "logi/commands/manual"
 require_relative "logi/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: logi-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dcode
@@ -110,8 +110,10 @@ files:
 - lib/logi.rb
 - lib/logi/cli.rb
 - lib/logi/commands/app.rb
+- lib/logi/commands/developer.rb
 - lib/logi/commands/device_login.rb
 - lib/logi/commands/login.rb
+- lib/logi/commands/manual.rb
 - lib/logi/commands/token.rb
 - lib/logi/config.rb
 - lib/logi/http_client.rb