DhanHQ 3.2.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 474564a108e478d3e2cc7bb0ad2b313a885b265ca3ece5091bd04dc1bb31b014
-  data.tar.gz: ab2a03010eb2ca03f7e6c9a01011b1b4b84f805611f22c55f7c2c07af1a7e063
+  metadata.gz: 287ad8c77adb3623574c0ee14102cfc3e88695168f75e1550a25dbbff9eb8508
+  data.tar.gz: a61b3f8e664f45f203b1afc3f840c9ed62a4e3c40e2f2d17fedc080ac682e029
 SHA512:
-  metadata.gz: 531c7d4fba8e753c2371569a47562ed32cd026c8a2828e28bb7b617f5f342bec870ace4fac6f95b4e122b360c164c42a65a34a90899e2e100b18e7cc594ffea0
-  data.tar.gz: 82332825d24456beeb67b61836472c05047ff323c3826f2f8324ac06ae036c10e9324788a43e1e7dbdcc74fb60cdbc385aaf373d99d851bb6732c51f6bf7638b
+  metadata.gz: 2c9ad1a3df906b585b0308809fb75235cf475a23c4eaddfea3f699de2e577819a1b78315b60012b6c51bb6c398dcaa35daab31d9ae9452d81d84e3e76741f0a9
+  data.tar.gz: 888e390276144b239a1bdd43afb9e77b58d21703587b898497b2426b8b78b47c7e03fd607bb3306fea49f9c2ae0e04a11ccb1b6968fc109fe61a8d2627b750a4

data/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+This is a pure-Ruby gem (no Rails, no running servers). Development commands are documented in `CLAUDE.md`.
+
+### Quick reference
+
+| Task | Command |
+|------|---------|
+| Install deps | `bundle install` |
+| Tests | `bundle exec rspec` |
+| Lint | `bundle exec rubocop` |
+| Both | `bundle exec rake` |
+| Single spec | `bundle exec rspec spec/path/to_spec.rb` |
+
+### Non-obvious caveats
+
+- **Bundler 4.x required**: The lockfile was bundled with Bundler 4.0.6. Install with `sudo gem install bundler -v 4.0.6` if missing.
+- **`libyaml-dev` must be installed**: The `psych` gem (transitive dep) needs `yaml.h`. Without `libyaml-dev`, `bundle install` fails on native extension build.
+- **`vendor/bundle` path**: Gems are installed to `./vendor/bundle` via `.bundle/config` to avoid needing root write access to `/var/lib/gems`.
+- **No real API calls in tests**: All HTTP interactions are stubbed with WebMock/VCR. No `DHAN_CLIENT_ID` or `DHAN_ACCESS_TOKEN` secrets are needed to run the test suite.
+- **No services to start**: This is a library gem. There is no web server, database, or background worker. Testing is purely `bundle exec rspec` / `bundle exec rubocop`.

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [3.2.1] - 2026-07-26
+
+### Fixed
+
+- **Restored the Claude Agent Skill pack to the published gem.** Switching `spec.files` from a reject-list to an allowlist in 3.2.0 stripped 51 MB of junk (a 36 MB core dump and a 17 MB `diagram.html`), but it also dropped `skills/dhanhq-ruby/` — 28 files, 164 KB: `SKILL.md` and its trigger frontmatter, 12 reference guides, 11 examples and 4 helper scripts. That pack is product content, added deliberately in #41. No Ruby code loads it at runtime, so nothing broke and no spec noticed; users installing 3.2.0 simply stopped receiving it. `CODE_OF_CONDUCT.md` and `AGENTS.md` are restored alongside it.
+
+  Unaffected and still shipped throughout: the MCP server (`lib/DhanHQ/mcp/`, `exe/dhanhq-mcp`), the agent tool layer (all 32 tools), the Ruby skills classes (`lib/DhanHQ/skills/`, 11 builtin skills), the risk pipeline and the WebSocket subsystem.
+
+  Gem size: 3.1.0 was 5.9 MB, 3.2.0 was 292 KB, and this is 324 KB. The 20× reduction is real and almost entirely the core dump; the skill pack was collateral.
+- **`DhanHQ::AI` was unreachable on a bare `require "dhan_hq"`.** The Zeitwerk inflector had no `ai → AI` acronym, so it looked for `DhanHQ::Ai` while `ai.rb` defines `DhanHQ::AI`; both spellings raised `NameError`. The documented `DhanHQ::AI::PromptHelpers` and `DhanHQ::AI::ContextBuilder` entry points therefore only worked if something had already loaded the file by hand, which only `mcp/server.rb` did. Found while writing the first specs for that module.
+
+### Added
+
+- **`spec/dhan_hq/gem_packaging_spec.rb`** — pins both ends of what ships, since packaging has now failed in both directions. Asserts the entry point, both executables, RBS signatures, Rails initializer, MCP server, agent tool layer, Ruby skills and the Claude Skill pack are all present; asserts the known junk, any crash dump, the spec suite and development config are all absent; and caps the uncompressed payload at 3 MB so a stray binary fails loudly rather than silently adding megabytes to a release.
+- First specs for `AI::PromptHelpers` (13 examples), covering portfolio summaries, the risk report's P&L arithmetic — summed across every position, counted only for open ones — and order confirmation rendering. Built on real model instances rather than doubles, because `BaseModel` defines attribute readers per instance and `instance_double` cannot verify them.
+- Specs for the lazily-built connection (not opened on construction, memoised, rebuilt on a base-URL change) and for retry exhaustion (transport errors translated, SDK errors re-raised unchanged, reads still retried).
+
+### Changed
+
+- **`Client#with_transient_retry` no longer duplicates its retry branch.** It had two rescue clauses running near-identical backoff-log-sleep-retry logic, differing only in what they raised once retries were spent. Collapsed into one clause, with an `exhausted_error` helper naming the difference: Faraday's transport errors are translated to `DhanHQ::NetworkError` (they are not part of this gem's hierarchy, so a caller rescuing `DhanHQ::Error` would otherwise miss them), while the gem's own errors are re-raised unchanged. Clears the `Lint/DuplicateBranch` pressure on this method.
+- **`Client#initialize` no longer opens a connection.** It now establishes state and checks its one invariant; the Faraday connection is built on first use of `#connection` and rebuilt when the configured base URL changes. Behaviour is unchanged for callers — `#connection` is still public and still reflects a sandbox toggle mid-process — but constructing a client does no network setup.
+- **`Naming/PredicateMethod` is now scoped by method name instead of by file.** Seven file-level exclusions replaced with `AllowedMethods: [cancel, modify, destroy]` plus `AllowBangMethods: true`.
+
+  These are commands that report whether they succeeded, not predicates — `cancel?` would read as "should I cancel?", which is worse than the name it replaces, so adding `?` aliases would have been the wrong fix. The unambiguous-failure path for them is the bang variant (`cancel!`, `modify!`). Scoping by name rather than by file also means a genuinely mis-named predicate elsewhere in those same files is still caught, and it surfaced a now-redundant inline `rubocop:disable` in `risk/pipeline.rb`.
+- `AI::PromptHelpers.portfolio_summary` computed the open-position set twice (`count(&:open?)` then `select(&:open?)`); it now derives it once. Both it and `.risk_report` wrap their collections in `Array()`, so a nil from a failed fetch renders an empty section instead of raising from inside a prompt helper — `funds` was already guarded, the collections were not.
+
 ## [3.2.0] - 2026-07-25
 
 ### Added

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/lib/DhanHQ/ai/prompt_helpers.rb

@@ -41,14 +41,20 @@ module DhanHQ
       # @param funds [DhanHQ::Models::Funds] Funds data
       # @return [String] Portfolio summary
       def self.portfolio_summary(holdings:, positions:, funds:)
+        # Array() so a missing collection renders as an empty section instead of
+        # raising. `funds` was already guarded; these two were not, and a prompt
+        # helper failing hard on an empty portfolio is the wrong trade.
+        all_holdings = Array(holdings)
+        open_positions = Array(positions).select(&:open?)
+
         lines = ["=== Portfolio Summary ==="]
         lines << "Funds: #{funds.to_prompt}" if funds
         lines << ""
-        lines << "Holdings (#{holdings.size}):"
-        holdings.each { |h| lines << "  #{h.to_prompt}" }
+        lines << "Holdings (#{all_holdings.size}):"
+        all_holdings.each { |holding| lines << "  #{holding.to_prompt}" }
         lines << ""
-        lines << "Open Positions (#{positions.count(&:open?)}):"
-        positions.select(&:open?).each { |p| lines << "  #{p.to_prompt}" }
+        lines << "Open Positions (#{open_positions.size}):"
+        open_positions.each { |position| lines << "  #{position.to_prompt}" }
         lines.join("\n")
       end
 
@@ -95,13 +101,17 @@ module DhanHQ
       # @param risk_params [Hash] Risk parameters
       # @return [String] Risk report
       def self.risk_report(positions:, risk_params: {})
+        # P&L is summed across every position; only the count is restricted to open
+        # ones, since a closed position still contributed realised P&L today.
+        all_positions = Array(positions)
+
         lines = ["=== Risk Report ==="]
-        total_unrealized = positions.sum { |p| p.unrealized_profit.to_f }
-        total_realized = positions.sum { |p| p.realized_profit.to_f }
+        total_unrealized = all_positions.sum { |position| position.unrealized_profit.to_f }
+        total_realized = all_positions.sum { |position| position.realized_profit.to_f }
 
         lines << "Total Unrealized P&L: ₹#{total_unrealized.round(2)}"
         lines << "Total Realized P&L: ₹#{total_realized.round(2)}"
-        lines << "Open Positions: #{positions.count(&:open?)}"
+        lines << "Open Positions: #{all_positions.count(&:open?)}"
 
         lines << "Max Drawdown: #{risk_params[:max_drawdown]}%" if risk_params[:max_drawdown]
 

data/lib/DhanHQ/client.rb

@@ -25,31 +25,57 @@ module DhanHQ
     include DhanHQ::RequestHelper
     include DhanHQ::ResponseHelper
 
-    # The Faraday connection object used for HTTP requests.
-    #
-    # @return [Faraday::Connection] The connection instance used for API requests.
-    attr_reader :connection
+    # Transient failures raised by this gem, worth retrying as-is.
+    RETRYABLE_SDK_ERRORS = [
+      DhanHQ::RateLimitError,
+      DhanHQ::InternalServerError,
+      DhanHQ::NetworkError
+    ].freeze
+    private_constant :RETRYABLE_SDK_ERRORS
+
+    # Transport failures raised by Faraday. Also worth retrying, but they are not part
+    # of this gem's error hierarchy, so a caller rescuing DhanHQ::Error would miss
+    # them — they are translated on the way out. See {#exhausted_error}.
+    RETRYABLE_TRANSPORT_ERRORS = [
+      Faraday::TimeoutError,
+      Faraday::ConnectionFailed
+    ].freeze
+    private_constant :RETRYABLE_TRANSPORT_ERRORS
 
     attr_reader :token_manager
 
-    # Initializes a new DhanHQ Client instance with a Faraday connection.
+    # Initializes a new DhanHQ Client.
+    #
+    # Establishes state and checks its one invariant; the HTTP connection is opened
+    # lazily on first use, so constructing a client does no network setup.
     #
     # @example Create a new client:
     #   client = DhanHQ::Client.new(api_type: :order_api)
     #
     # @param api_type [Symbol] Type of API (`:order_api`, `:data_api`, `:non_trading_api`)
     # @return [DhanHQ::Client] A new client instance.
-    # @raise [DhanHQ::Error] If configuration is invalid or rate limiter initialization fails
+    # @raise [DhanHQ::Error] If the rate limiter cannot be resolved for this API type.
     def initialize(api_type:)
       DhanHQ.ensure_configuration!
-      # Use shared rate limiter instance per API type to ensure proper coordination
+      # Shared per API type, so separate clients coordinate against one limit.
       @rate_limiter = RateLimiter.for(api_type)
 
       raise DhanHQ::Error, "RateLimiter initialization failed" unless @rate_limiter
+    end
+
+    # The Faraday connection used for HTTP requests.
+    #
+    # Built on first use and rebuilt whenever the configured base URL changes — which
+    # happens when sandbox mode is toggled, or when a token endpoint hands back a
+    # different host mid-process.
+    #
+    # @return [Faraday::Connection]
+    def connection
+      current_url = DhanHQ.configuration.base_url
+      return @connection if @connection && @last_base_url == current_url
 
-      # Store initial URL to detect changes
-      @last_base_url = DhanHQ.configuration.base_url
-      @connection = build_connection(@last_base_url)
+      @last_base_url = current_url
+      @connection = build_connection(current_url)
     end
 
     # Sends an HTTP request to the API with automatic retry for transient errors.
@@ -66,7 +92,6 @@ module DhanHQ
 
       @token_manager&.ensure_valid_token!
       @rate_limiter.throttle!
-      refresh_connection!
 
       # A non-idempotent write is not safely retryable: the API has no idempotency
       # key, so a request that timed out may already have reached the exchange.
@@ -99,27 +124,13 @@ module DhanHQ
       attempt = 0
       begin
         yield
-      rescue DhanHQ::RateLimitError, DhanHQ::InternalServerError, DhanHQ::NetworkError => e
-        attempt += 1
-        raise if attempt > retries
-
-        backoff = calculate_backoff(attempt)
-        DhanHQ.logger&.warn(
-          "[DhanHQ::Client] Transient error (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
-        )
-        sleep(backoff)
-        retry
-      rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+      rescue *RETRYABLE_SDK_ERRORS, *RETRYABLE_TRANSPORT_ERRORS => e
         attempt += 1
-        if attempt > retries
-          raise DhanHQ::NetworkError, "Request failed: #{e.message}" if retries.zero?
-
-          raise DhanHQ::NetworkError, "Request failed after #{retries} retries: #{e.message}"
-        end
+        raise exhausted_error(e, retries) if attempt > retries
 
         backoff = calculate_backoff(attempt)
         DhanHQ.logger&.warn(
-          "[DhanHQ::Client] Network error (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
+          "[DhanHQ::Client] Transient failure (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
         )
         sleep(backoff)
         retry
@@ -253,12 +264,20 @@ module DhanHQ
       out
     end
 
-    def refresh_connection!
-      current_url = DhanHQ.configuration.base_url
-      return if @last_base_url == current_url
-
-      @last_base_url = current_url
-      @connection = build_connection(current_url)
+    # The exception to raise once the retries are spent.
+    #
+    # Faraday's transport errors are translated to {DhanHQ::NetworkError}, so a caller
+    # rescuing DhanHQ::Error sees every failure this client can produce. This gem's own
+    # errors already belong to that hierarchy and are re-raised unchanged.
+    #
+    # @param error [StandardError] The failure that exhausted the retries.
+    # @param retries [Integer] How many retries were allowed.
+    # @return [StandardError] The exception to raise.
+    def exhausted_error(error, retries)
+      return error unless RETRYABLE_TRANSPORT_ERRORS.any? { |klass| error.is_a?(klass) }
+
+      attempts = retries.zero? ? "" : " after #{retries} retries"
+      DhanHQ::NetworkError.new("Request failed#{attempts}: #{error.message}")
     end
 
     def build_connection(url)

data/lib/DhanHQ/models/alert_order.rb

@@ -96,7 +96,7 @@ module DhanHQ
         handle_api_response(response, success_key: new_record? ? "alertId" : nil)
       end
 
-      def destroy # rubocop:disable Naming/PredicateMethod
+      def destroy
         return false if new_record?
 
         response = self.class.resource.delete(id)

data/lib/DhanHQ/risk/pipeline.rb

@@ -51,14 +51,12 @@ module DhanHQ
       # @param type [Symbol] :equity or :options
       # @return [true] if all checks pass
       # @raise [DhanHQ::RiskViolation] on first failure
-      # rubocop:disable Naming/PredicateMethod
       def self.run!(instrument:, args:, now: Time.now, type: :equity)
         run_checks!(CHECKS, instrument, args, now)
         run_checks!(OPTION_CHECKS, instrument, args, now) if type == :options
         run_checks!(DAILY_CHECKS, instrument, args, now)
         true
       end
-      # rubocop:enable Naming/PredicateMethod
 
       def self.run_checks!(checks, instrument, args, now)
         checks.each do |check|

data/lib/DhanHQ/version.rb

@@ -2,5 +2,5 @@
 
 module DhanHQ
   # Semantic version of the DhanHQ client gem.
-  VERSION = "3.2.0"
+  VERSION = "3.2.1"
 end

data/lib/dhan_hq.rb

@@ -26,6 +26,10 @@ module DhanHQ
   LOADER = Zeitwerk::Loader.new
   LOADER.tag = "dhanhq"
   LOADER.inflector.inflect(
+    # Without this, Zeitwerk looks for DhanHQ::Ai while ai.rb defines DhanHQ::AI, so
+    # DhanHQ::AI::PromptHelpers raised NameError unless something had already loaded
+    # the file by hand — which only mcp/server.rb did.
+    "ai" => "AI",
     "api_helper" => "APIHelper",
     "auth_api" => "AuthAPI",
     "base_api" => "BaseAPI",

data/skills/dhanhq-ruby/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: dhanhq-ruby
+description: >
+  Use when the user mentions DhanHQ, Dhan API, or wants to trade on
+  Indian exchanges (NSE, BSE, MCX) using Ruby. Triggers for: place, modify, or
+  cancel stock/F&O/commodity orders on Dhan using Ruby; fetch portfolio holdings
+  or positions; get live or historical market data; access option
+  chains with Greeks; check fund limits or margin; build any trading
+  automation for Indian markets; resolve NSE/BSE instrument IDs;
+  stream live WebSocket market feeds or order updates. Also trigger
+  for general questions about programmatic trading on Indian exchanges
+  if Dhan is the user's broker.
+compatibility: >
+  Requires Ruby and the dhanhq gem.
+  Order placement, modification, and cancellation require static IP
+  whitelisting on Dhan. Data APIs (quotes, history, option chain,
+  live feed) require an active Dhan Data Plan.
+---
+
+# DhanHQ — Indian Market Trading Skill (Ruby SDK)
+
+Use this skill when an agent needs to write, review, or operate Ruby code using the `DhanHQ` gem.
+
+## Safety Rules — Always Enforce
+
+1. Confirm before placing live orders.
+2. Show a readable order preview before execution.
+3. Default to `LIMIT` orders unless the user explicitly wants `MARKET`.
+4. Warn when notional exceeds `Rs. 50,000`.
+5. For F&O, validate lot size before placement.
+6. Never use `CNC` or `MTF` for F&O, commodity, or currency segments.
+7. Never hardcode credentials in generated code.
+8. Ask for confirmation before modifying or cancelling orders, or performing multi-leg live execution.
+
+## Setup
+
+Require the core library and configure using environment variables or a configuration block:
+
+```ruby
+require "dhan_hq"
+
+# Configures from environment variables: DHAN_CLIENT_ID, DHAN_ACCESS_TOKEN
+DhanHQ.configure_with_env
+```
+
+Or configure explicitly:
+
+```ruby
+DhanHQ.configure do |config|
+  config.client_id = "YOUR_CLIENT_ID"
+  config.access_token = "YOUR_ACCESS_TOKEN"
+end
+```
+
+If generating scripts inside this repo, prefer using the helper script:
+
+```ruby
+require_relative "scripts/dhan_helpers"
+get_client
+```
+
+## Current SDK Constants
+
+Use constants from the `DhanHQ::Constants` module for segments, order types, validity, product types, and transactions:
+
+| Category | Constant | Value |
+|----------|----------|-------|
+| Exchange Segment | `DhanHQ::Constants::ExchangeSegment::NSE_EQ` (or `DhanHQ::Constants::NSE`) | `"NSE_EQ"` |
+| | `DhanHQ::Constants::ExchangeSegment::BSE_EQ` (or `DhanHQ::Constants::BSE`) | `"BSE_EQ"` |
+| | `DhanHQ::Constants::ExchangeSegment::NSE_FNO` (or `DhanHQ::Constants::NSE_FNO` / `DhanHQ::Constants::FNO`) | `"NSE_FNO"` |
+| | `DhanHQ::Constants::ExchangeSegment::BSE_FNO` (or `DhanHQ::Constants::BSE_FNO`) | `"BSE_FNO"` |
+| | `DhanHQ::Constants::ExchangeSegment::MCX_COMM` (or `DhanHQ::Constants::MCX`) | `"MCX_COMM"` |
+| | `DhanHQ::Constants::ExchangeSegment::IDX_I` (or `DhanHQ::Constants::INDEX`) | `"IDX_I"` |
+| Transaction Type | `DhanHQ::Constants::TransactionType::BUY` (or `DhanHQ::Constants::BUY`) | `"BUY"` |
+| | `DhanHQ::Constants::TransactionType::SELL` (or `DhanHQ::Constants::SELL`) | `"SELL"` |
+| Order Type | `DhanHQ::Constants::OrderType::LIMIT` (or `DhanHQ::Constants::LIMIT`) | `"LIMIT"` |
+| | `DhanHQ::Constants::OrderType::MARKET` (or `DhanHQ::Constants::MARKET`) | `"MARKET"` |
+| | `DhanHQ::Constants::OrderType::STOP_LOSS` (or `DhanHQ::Constants::SL`) | `"STOP_LOSS"` |
+| | `DhanHQ::Constants::OrderType::STOP_LOSS_MARKET` (or `DhanHQ::Constants::SLM`) | `"STOP_LOSS_MARKET"` |
+| Product Type | `DhanHQ::Constants::ProductType::CNC` (or `DhanHQ::Constants::CNC`) | `"CNC"` |
+| | `DhanHQ::Constants::ProductType::INTRADAY` (or `DhanHQ::Constants::INTRA`) | `"INTRADAY"` |
+| | `DhanHQ::Constants::ProductType::MARGIN` (or `DhanHQ::Constants::MARGIN`) | `"MARGIN"` |
+| | `DhanHQ::Constants::ProductType::MTF` (or `DhanHQ::Constants::MTF`) | `"MTF"` |
+| Validity | `DhanHQ::Constants::Validity::DAY` (or `DhanHQ::Constants::DAY`) | `"DAY"` |
+| | `DhanHQ::Constants::Validity::IOC` (or `DhanHQ::Constants::IOC`) | `"IOC"` |
+
+## Preferred SDK Methods (ActiveRecord-Style Models)
+
+| Task | Method |
+|------|--------|
+| Place order | `DhanHQ::Models::Order.place(params)` |
+| List all orders | `DhanHQ::Models::Order.all` |
+| Order by ID | `DhanHQ::Models::Order.find(order_id)` |
+| Order by correlation ID | `DhanHQ::Models::Order.find_by_correlation(correlation_id)` |
+| Today's trades | `DhanHQ::Models::Trade.today` |
+| Historical trades | `DhanHQ::Models::Trade.history(from_date:, to_date:, page:)` |
+| Holdings | `DhanHQ::Models::Holding.all` |
+| Positions | `DhanHQ::Models::Position.all` |
+| Fund limits | `DhanHQ::Models::Funds.fetch` |
+| Margin calculator | `DhanHQ::Models::Margin.calculate(params)` |
+| Multi-instrument margin | `DhanHQ::Models::Margin.calculate_multi(params)` |
+| Daily charts | `DhanHQ::Models::HistoricalData.daily(params)` |
+| Intraday charts | `DhanHQ::Models::HistoricalData.intraday(params)` |
+| Option chain | `DhanHQ::Models::OptionChain.fetch(params)` |
+| Expiry list | `DhanHQ::Models::OptionChain.fetch_expiry_list(params)` |
+| Search instruments | `DhanHQ::Models::Instrument.search(query, options)` |
+| Find specific instrument by symbol | `DhanHQ::Models::Instrument.find(exchange_segment, symbol, options)` |
+| Find specific instrument by security ID | `DhanHQ::Models::Instrument.find_by_security_id(exchange_segment, security_id)` |
+| Find instrument anywhere | `DhanHQ::Models::Instrument.find_anywhere(symbol, options)` |
+| Super orders | `DhanHQ::Models::SuperOrder.create(params)` |
+| Forever orders | `DhanHQ::Models::ForeverOrder.create(params)` |
+| Live market feed | `DhanHQ::WS.connect(mode: :ticker) { |tick| ... }` |
+| Live order updates | `DhanHQ::WS::Orders.connect { |update| ... }` |
+| Live market depth | `DhanHQ::WS::MarketDepth.connect(symbols: [{...}]) { |depth| ... }` |
+
+## High-Value Gotchas
+
+- **Return values are model instances:** Most class methods return `DhanHQ::Models` objects rather than raw HTTP hashes.
+- **Instrument search is segment-specific:** `DhanHQ::Models::Instrument.by_segment(exchange_segment)` downloads the CSV for a single segment, which is more token-efficient than downloading the entire master CSV.
+- **Spelling fixes in models:** Typos from the Dhan API are normalized in model attributes (e.g. `availabelBalance` is normalized to `available_balance` or `availabel_balance`).
+- **Timestamps:** Timestamps returned by `HistoricalData` are automatically normalized into Ruby `Time` objects.
+- **WebSocket connection management:** Use sequential connections or single connection pools to avoid 429 rate limiting. Dhan allows up to 5 concurrent WebSocket connections.
+
+## Core Patterns
+
+### 1. Check account access before data calls
+
+```ruby
+funds = DhanHQ::Models::Funds.fetch
+puts "Available Balance: Rs. #{funds.availabel_balance}"
+```
+
+### 2. Fetch historical data
+
+```ruby
+candles = DhanHQ::Models::HistoricalData.daily(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  instrument: "EQUITY",
+  from_date: "2024-01-01",
+  to_date: "2024-12-31"
+)
+
+candles.each do |candle|
+  puts "Date: #{candle[:timestamp].to_date}, Close: #{candle[:close]}"
+end
+```
+
+### 3. Option-chain data
+
+```ruby
+chain = DhanHQ::Models::OptionChain.fetch(
+  underlying_scrip: 13,
+  underlying_seg: "IDX_I",
+  expiry: "2025-03-27"
+)
+
+puts "Underlying spot: #{chain[:last_price]}"
+chain[:strikes].each do |strike_data|
+  puts "Strike: #{strike_data[:strike]}, Call LTP: #{strike_data[:call][:last_price]}"
+end
+```
+
+### 4. Margin check before live order placement
+
+```ruby
+margin = DhanHQ::Models::Margin.calculate(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  transaction_type: "BUY",
+  quantity: 10,
+  product_type: "CNC",
+  price: 2450.0
+)
+
+puts "Sufficient balance? #{margin.available_balance >= margin.total_margin}"
+```
+
+### 5. Live market feed
+
+```ruby
+market_client = DhanHQ::WS.connect(mode: :ticker) do |tick|
+  puts "Market Tick: #{tick[:security_id]} = #{tick[:ltp]}"
+end
+
+market_client.subscribe_one(segment: "NSE_EQ", security_id: "2885")
+sleep(10)
+market_client.stop
+```
+
+## Reference Files
+
+Refer to the documents in the references directory for focused workflows:
+
+| Need | File |
+|------|------|
+| Orders, super orders, forever orders | [references/orders.md](references/orders.md) |
+| Holdings, positions, eDIS | [references/portfolio.md](references/portfolio.md) |
+| Daily/minute history, quotes, expired options | [references/market-data.md](references/market-data.md) |
+| Option-chain usage | [references/option-chain.md](references/option-chain.md) |
+| Fund limits and margin checks | [references/funds.md](references/funds.md) |
+| Live feeds and depth | [references/live-feed.md](references/live-feed.md) |
+| Error handling | [references/error-codes.md](references/error-codes.md) |
+| Instrument resolution | [references/instruments.md](references/instruments.md) |
+| Multi-step execution patterns | [references/common-workflows.md](references/common-workflows.md) |
+| Options analytics | [references/options-analysis-patterns.md](references/options-analysis-patterns.md) |
+| Backtesting patterns | [references/backtesting-with-dhan.md](references/backtesting-with-dhan.md) |
+| Extranal data sources (RSI, PE ratios, screener) | [references/scanx-data.md](references/scanx-data.md) |