feat(docs): improve docs

[prajjwalkumar17]

This pull request updates the documentation for the Decision Engine project, focusing on improving clarity, accuracy, and usability of both the README and API reference. The README now better describes the product's capabilities and use cases, while the API reference and endpoint documentation have been expanded with detailed descriptions, authentication instructions, request/response examples, and improved internal linking. These changes enhance the onboarding experience for new users and make the API easier to navigate and understand.

README improvements:

• Updated product description and tagline in README.md to clarify the Decision Engine’s focus on rule-based, Rust-powered, and success-rate-based payment routing. [1] [2]
• Replaced the "Why Teams Choose" section with a "Core Use Cases" table, highlighting supported routing strategies and analytics.
• Revised the operational capabilities section to better describe dashboard, API, analytics, and deployment surfaces; removed the outdated "Performance at a Glance" section.

API reference navigation and linking:

• Changed all endpoint links in docs/api-reference.md from absolute to relative paths, and updated them to point to .mdx files for better navigation in the docs site.

Endpoint documentation enhancements:

• Added detailed descriptions, authentication instructions, usage examples, and related links to the following endpoints:
  • activateRoutingRule.mdx
  • analyticsOverview.mdx
  • analyticsGatewayScores.mdx
  • analyticsDecisions.mdx
  • analyticsLogSummaries.mdx

[Copilot]

Pull request overview

This PR updates the Decision Engine documentation to improve API navigation and provide richer per-endpoint reference pages (use cases, auth, request/response examples, and cross-linking) alongside a few docs-site configuration/link adjustments.

Changes:

• Updates Mintlify docs configuration and selected docs links.
• Converts API Examples links to use relative .mdx paths for better internal navigation.
• Expands OpenAPI-backed endpoint reference pages with detailed descriptions, auth guidance, examples, and related links.

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
docs/mint.json	Updates Mintlify configuration (removes top-level openapi entry).
docs/configuration.md	Updates Helm chart reference link to GitHub.
docs/api-refs/api-ref.mdx	Updates internal links to relative .mdx/.md paths.
docs/api-refs/decision-gateway-legacy.mdx	Updates internal link to relative .mdx path.
docs/api-refs/update-score-legacy.mdx	Updates internal link to relative .mdx path.
docs/api-reference/endpoint/activateRoutingRule.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/analyticsDecisions.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/analyticsGatewayScores.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/analyticsLogSummaries.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/analyticsOverview.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/analyticsPaymentAudit.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/analyticsPreviewTrace.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/analyticsRoutingStats.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/configSrDimension.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/createApiKey.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/createMerchant.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/createRoutingRule.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/createRuleConfig.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/decideGateway.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/deleteMerchant.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/deleteRuleConfig.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/evaluateRoutingRule.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/getActiveRoutingRule.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/getMerchant.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/getMerchantDebitRouting.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/getRoutingConfig.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/getRuleConfig.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/healthCheck.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/healthDiagnostics.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/healthReady.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/hybridRouting.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/legacyDecisionGateway.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/legacyUpdateScore.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/listApiKeys.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/listRoutingRules.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/listUserMerchants.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/login.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/logout.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/me.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/onboardMerchant.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/revokeApiKey.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/signup.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/switchMerchant.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/updateGatewayScore.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/updateMerchantDebitRouting.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.
docs/api-reference/endpoint/updateRuleConfig.mdx	Adds expanded endpoint documentation and OpenAPI binding metadata.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The authentication section is inconsistent with docs/openapi.json: /merchant-account/create is secured with AdminSecret (header x-admin-secret), not JWT/API-key auth. This is important because following the current doc will result in authorization failures and may encourage using the wrong credential type.

[Copilot]

The response example is wrapped in a { "keys": [...] } object, but docs/openapi.json specifies the 200 response for this endpoint as a bare JSON array of ApiKeyListItem. Consider updating the response example to match the actual shape (and include fields like key_prefix / is_active if relevant).

Suggested change

	{
	"keys": [
	{
	"key_id": "key_123",
	"merchant_id": "merchant_demo",
	"name": "local-smoke-key",
	"created_at": "2026-04-26T00:00:00Z"
	}
	]
	}
	[
	{
	"key_id": "key_123",
	"merchant_id": "merchant_demo",
	"name": "local-smoke-key",
	"key_prefix": "pk_dev_1234",
	"is_active": true,
	"created_at": "2026-04-26T00:00:00Z"
	}
	]

[Copilot]

Per docs/openapi.json, GET /auth/merchants returns a JSON array of MerchantInfo objects, not an object with a merchants key. Updating this response example to match the OpenAPI shape will prevent copy/paste parsing errors for consumers.

[Copilot]

The response example (merchant_id, config_type, deleted) doesn't match docs/openapi.json, where /rule/delete returns DeleteResponse (currently just a message). Please update the response example to reflect what the endpoint actually returns per the OpenAPI spec.

Suggested change

	"merchant_id": "merchant_demo",
	"config_type": "successRate",
	"deleted": true
	"message": "Rule config deleted successfully"

[Copilot]

status: "success" is not a valid value per openapi.json for the legacy /update-score endpoint (it reuses UpdateGatewayScoreRequest, where status is an enum like CHARGED, AUTHENTICATION_FAILED, etc.). Update the example request (and any response fields that depend on it) to use the documented enum values so the curl command is executable.

Suggested change

	"status": "success"
	"status": "CHARGED"

[Copilot]

The response example ({ deleted: true, merchant_id: ... }) doesn't match docs/openapi.json, which defines DELETE /merchant-account/{merchantId} as returning DeleteResponse (currently just a message). Please update the response example to reflect the OpenAPI contract so consumers don't build against a non-existent deleted field.

Suggested change

	"deleted": true,
	"merchant_id": "merchant_demo"
	"message": "Merchant deleted successfully"

[Copilot]

The response example here doesn't match docs/openapi.json: POST /auth/switch-merchant returns AuthResponse (token, user_id, email, merchant_id, role, merchants array), not { token, merchant_id, merchant_name }. Please align the documented response shape with the OpenAPI contract so dashboard/client implementations handle the right fields.

[Copilot]

The success-rate and elimination config.data examples here use fields like min_aggregates_size, default_success_rate, bucket_size, and threshold, but the existing curl examples in docs/api-refs/* (and the OpenAPI examples) use camelCase fields like defaultBucketSize, defaultLatencyThreshold, bucketSize, and eliminationThreshold. Please align these examples with the established request shapes so users don't send unsupported fields.

[Copilot]

The response example (config_type + message) doesn't match docs/openapi.json, where /rule/create returns RuleConfigResponse (with merchant_id and config). Consider updating the response example to reflect the actual returned object so clients can parse it correctly.

Suggested change

	"config_type": "successRate",
	"message": "rule config created"
	"config": {
	"type": "successRate",
	"data": {
	"enabled": true,
	"min_aggregates_size": 5,
	"default_success_rate": 0.8,
	"specificity_level": "merchant"
	}
	}

[Copilot]

docs/openapi.json defines the 200 response for POST /routing/list/{created_by} as a JSON array of RoutingRule, but this page documents { "rules": [...] }. Updating the response example to match the OpenAPI shape will prevent consumers from building against the wrong response contract.

Suggested change

	{
	"rules": [
	{
	"rule_id": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0",
	"name": "priority rule",
	"active": true,
	"algorithm_for": "payment"
	}
	]
	}
	[
	{
	"rule_id": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0",
	"name": "priority rule",
	"active": true,
	"algorithm_for": "payment"
	}
	]