tradingcodex 1.1.2__tar.gz → 1.2.1__tar.gz

{tradingcodex-1.1.2 → tradingcodex-1.2.1}/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 ## Unreleased
 
+## 1.2.1 - 2026-07-21
+
+- Create or refresh the GitHub Release from the exact verified distributions
+  and matching changelog section only after protected PyPI publication succeeds.
+- Run Python and frontend CI gates in parallel, verify releases on Apple Silicon
+  macOS, retain temporary distributions for seven days, remove the duplicate
+  Ubuntu wheel smoke, and reduce upgrade validation to the latest public
+  predecessor-to-candidate path.
+
+- Let users author Investor Context directly with native Codex while retaining
+  lifecycle protection for enable, disable, and clear operations.
+- Judge research evidence by the claim, intended use, and update cadence rather
+  than by an official-versus-available source label; preserve valid partial
+  fields and fetch only the missing decision-relevant coverage.
+- Remove the generic analysis prompt-submit hook from ordinary requests while
+  retaining grant revocation and reserved safety actions.
+- For short-horizon directional questions, resolve the relevant market session
+  and include market-wide or macro expertise when transmission could materially
+  change direction, range, or scenario weights without imposing a fixed roster.
+
+## 1.2.0 - 2026-07-20
+
+- Refresh the manual GitHub Pages workflow to the current Node 24 action
+  majors after the v1.1.2 candidate exposed the upstream Node 20 deprecation
+  annotation. The guide remains explicit-dispatch only.
+- Simplify Codex-native orchestration, hooks, and lifecycle boundaries while
+  retaining concise fixed-role prompts, direct native delegation, and
+  service-gated sensitive effects.
+- Keep root work on the user's active Codex model and reasoning settings while
+  fixed roles use `gpt-5.6-terra`/high, including explicit independent risk and
+  judgment review boundaries.
+- Preserve canonical research-artifact lookup when a supported export copies
+  Markdown between research and report paths. Current exports carry a
+  service-authenticated sidecar bound to central workspace provenance, while
+  pre-1.2 copies are recovered only when a retained signed receipt and, when
+  needed, a version archive prove the original path and bytes; altered,
+  replayed, copied-root, or ambiguous duplicates remain fail-closed.
+- Require the same central workspace provenance for every run-bound receipt
+  read, including compact review and card projections, so a copied workspace
+  cannot replay authenticated research with a shared local service key.
+- Keep optional OpenBB direct, add Snapshot/Dataset row-oriented reuse, and
+  strengthen conclusion-relevant point-in-time evidence, decision quality, and
+  artifact handoff guidance without adding provider or workflow services.
+- Add agent-maintained, Obsidian-compatible Knowledge Wikis with explicit write
+  admission, immutable community packages, bounded read-only Viewer search,
+  and a separate Brain-promotion boundary.
+- Record redacted external-tool observations for offline exact-repeat regression
+  checks; they do not infer outcome or block native tool use.
+
 ## 1.1.2 - 2026-07-17
 
 - Add a cross-platform fixed-role calculation surface with generated

{tradingcodex-1.1.2 → tradingcodex-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 1.1.2
+Version: 1.2.1
 Summary: Local-first investment operating system for Codex-native research and service-gated execution.
 Author: TradingCodex Authors
 License-Expression: Apache-2.0
@@ -59,7 +59,7 @@ next steps in your own workspace.
 It is not an autonomous trading bot. A research response never becomes a
 broker action on its own.
 
-[Get started](https://monarchjuno.github.io/tradingcodex/) · [All user-facing skills](docs/user-facing-skills.md) · [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) · [Documentation](docs/README.md)
+[Get started](https://monarchjuno.github.io/tradingcodex/) · [Data sources and OpenBB](docs/data-sources-and-openbb.md) · [All user-facing skills](docs/user-facing-skills.md) · [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) · [Documentation](docs/README.md)
 
 ## Start Here
 
@@ -106,7 +106,8 @@ need Node, npm, or a separate frontend server.
 | Review a past decision or validate a lesson | [`$tcx-memory`](https://monarchjuno.github.io/tradingcodex/skill-memory.html) | Replay from point-in-time evidence and distinguish decision quality from outcome quality. |
 | Create a reusable method or reasoning framework | [`$tcx-strategy`](https://monarchjuno.github.io/tradingcodex/skill-strategy.html) or [`$tcx-brain`](https://monarchjuno.github.io/tradingcodex/skill-brain.html) | Start directly with the matching skill in the normal Research profile; its current-turn scope cannot grant execution authority or cross into generic Build work. |
 | Monitor work on a schedule | [`$tcx-automate`](https://monarchjuno.github.io/tradingcodex/skill-automate.html) | Create or update a Codex Scheduled Task that invokes the actual work skill on each run. |
-| Open the dashboard or recover a workspace | [`$tcx-dashboard`](https://monarchjuno.github.io/tradingcodex/skill-dashboard.html) or [`$tcx-server`](https://monarchjuno.github.io/tradingcodex/skill-server.html) | Open the read-only viewer inside Codex by default, request an external browser when needed, or receive a readiness check and safe recovery handoff. |
+| Open the viewer or recover a workspace | The Viewer and Wiki links shown when a healthy workspace task starts, or [`$tcx-server`](https://monarchjuno.github.io/tradingcodex/skill-server.html) | Follow the read-only links directly; use the server skill for readiness checks and safe recovery guidance. |
+| Configure optional OpenBB data access | [Data sources](https://monarchjuno.github.io/tradingcodex/data-sources.html) | OpenBB is projected by default as a non-required direct MCP; use `tcx data-sources openbb status|disable|enable` to control it. It is never installed during attach. |
 | Connect a provider and prepare an order | [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) | Keep provider setup, account sync, ticket creation, checks, approval, and final action as separate checkpoints. |
 
 There are 13 user-facing skills. Browse their detailed behavior, examples, and
@@ -123,16 +124,16 @@ Analyze MSFT as a medium-term quality compounder. Separate facts, inferences,
 and assumptions. Include contrary evidence and invalidation conditions. No order.
 ```
 
-The workflow begins a lightweight, workspace-bound run. Head Manager selects
-only the fixed-role specialists the question needs, reassesses from accepted
-artifacts, and either synthesizes the result or states why work is waiting,
-needs revision, or is blocked.
+Narrow trusted questions can stay direct. Fresh research begins a lightweight,
+workspace-bound run; Head Manager selects only useful specialist profiles,
+uses bounded fallback when necessary, and reassesses from accepted evidence
+before answering, synthesizing, revising, or stopping on a gap.
 
 ## How TradingCodex Is Organized
 
 | Layer | What it does | What it does not do |
 | --- | --- | --- |
-| **Native Codex task** | Interprets the request, runs Head Manager, and dynamically dispatches exact fixed-role specialists. | It does not turn ordinary prose into an order or use a generic agent to imitate a specialist. |
+| **Native Codex task** | Interprets the request, takes a direct fast path when sufficient, and uses specialist profiles or a bounded generic child only when needed. | It does not turn ordinary prose, a child, or a skill into policy, approval, broker, or execution authority. |
 | **Workspace** | Holds readable research, reports, source snapshots, skills, prompts, and lightweight run provenance. | It is not the portfolio, order, account, approval, or secret ledger. |
 | **Django service** | Enforces artifact identity, policy, approval, broker, idempotency, execution, and audit rules through shared application services. | It does not replace Codex with a semantic router, preset team, or stored workflow DAG. |
 | **Read-only viewer** | Lets you browse Library artifacts, Skills, System posture, and registered workspaces. | It does not launch Codex, write workspace files, or mutate orders, brokers, skills, or policy. |
@@ -161,11 +162,11 @@ that state in prompts or workspace files.
 - Fixed roles have bounded tools and handoff responsibilities. A final order
   path is available only from an exact root-native protocol, never from the
   viewer, a subagent, public REST, generic CLI, or direct MCP call.
-- User-installed MCP servers, skills, and plugins are BYOR native Codex
-  capabilities. TradingCodex neither recommends nor verifies them; their
-  licenses, data terms, costs, and side effects remain the user/provider's
-  responsibility, and TradingCodex guarantees cover only its own capabilities,
-  state, and actions.
+- Relevant user-installed MCP servers and skills remain BYOR native Codex
+  capabilities. One relevant capability can be used for evidence without
+  becoming TradingCodex-managed. OpenBB is the one TradingCodex-supported
+  external data integration: it is optional, projected directly to evidence
+  roles, and still subject to upstream licenses and data terms.
 - Raw credentials do not belong in prompts, workspace files, reports, API/MCP
   output, or audit data.
 
@@ -180,6 +181,7 @@ guarantee returns.
 | [User Guide](https://monarchjuno.github.io/tradingcodex/) | Setup, examples, concepts, all user-facing skills, and provider-to-order onboarding. |
 | [Installation](installation.md) | Install variants, updates, runtime homes, MCP/service startup, and recovery. |
 | [User-facing skills](docs/user-facing-skills.md) | The full skill map, entry rules, and hard stops. |
+| [Data sources and OpenBB](docs/data-sources-and-openbb.md) | Source routing, direct optional OpenBB projection, Snapshot/Dataset evidence, and third-party terms. |
 | [Research memory and artifacts](docs/research-memory-and-artifacts.md) | Artifact paths, source posture, versions, quality labels, forecasts, and exports. |
 | [Decision memory](docs/decision-memory.md) | Replay, postmortems, lesson validation, and reusable context. |
 | [Safety policy and execution](docs/safety-policy-and-execution.md) | Permissions, approvals, brokers, secrets, and execution boundaries. |

{tradingcodex-1.1.2 → tradingcodex-1.2.1}/README.md

@@ -21,7 +21,7 @@ next steps in your own workspace.
 It is not an autonomous trading bot. A research response never becomes a
 broker action on its own.
 
-[Get started](https://monarchjuno.github.io/tradingcodex/) · [All user-facing skills](docs/user-facing-skills.md) · [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) · [Documentation](docs/README.md)
+[Get started](https://monarchjuno.github.io/tradingcodex/) · [Data sources and OpenBB](docs/data-sources-and-openbb.md) · [All user-facing skills](docs/user-facing-skills.md) · [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) · [Documentation](docs/README.md)
 
 ## Start Here
 
@@ -68,7 +68,8 @@ need Node, npm, or a separate frontend server.
 | Review a past decision or validate a lesson | [`$tcx-memory`](https://monarchjuno.github.io/tradingcodex/skill-memory.html) | Replay from point-in-time evidence and distinguish decision quality from outcome quality. |
 | Create a reusable method or reasoning framework | [`$tcx-strategy`](https://monarchjuno.github.io/tradingcodex/skill-strategy.html) or [`$tcx-brain`](https://monarchjuno.github.io/tradingcodex/skill-brain.html) | Start directly with the matching skill in the normal Research profile; its current-turn scope cannot grant execution authority or cross into generic Build work. |
 | Monitor work on a schedule | [`$tcx-automate`](https://monarchjuno.github.io/tradingcodex/skill-automate.html) | Create or update a Codex Scheduled Task that invokes the actual work skill on each run. |
-| Open the dashboard or recover a workspace | [`$tcx-dashboard`](https://monarchjuno.github.io/tradingcodex/skill-dashboard.html) or [`$tcx-server`](https://monarchjuno.github.io/tradingcodex/skill-server.html) | Open the read-only viewer inside Codex by default, request an external browser when needed, or receive a readiness check and safe recovery handoff. |
+| Open the viewer or recover a workspace | The Viewer and Wiki links shown when a healthy workspace task starts, or [`$tcx-server`](https://monarchjuno.github.io/tradingcodex/skill-server.html) | Follow the read-only links directly; use the server skill for readiness checks and safe recovery guidance. |
+| Configure optional OpenBB data access | [Data sources](https://monarchjuno.github.io/tradingcodex/data-sources.html) | OpenBB is projected by default as a non-required direct MCP; use `tcx data-sources openbb status|disable|enable` to control it. It is never installed during attach. |
 | Connect a provider and prepare an order | [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) | Keep provider setup, account sync, ticket creation, checks, approval, and final action as separate checkpoints. |
 
 There are 13 user-facing skills. Browse their detailed behavior, examples, and
@@ -85,16 +86,16 @@ Analyze MSFT as a medium-term quality compounder. Separate facts, inferences,
 and assumptions. Include contrary evidence and invalidation conditions. No order.
 ```
 
-The workflow begins a lightweight, workspace-bound run. Head Manager selects
-only the fixed-role specialists the question needs, reassesses from accepted
-artifacts, and either synthesizes the result or states why work is waiting,
-needs revision, or is blocked.
+Narrow trusted questions can stay direct. Fresh research begins a lightweight,
+workspace-bound run; Head Manager selects only useful specialist profiles,
+uses bounded fallback when necessary, and reassesses from accepted evidence
+before answering, synthesizing, revising, or stopping on a gap.
 
 ## How TradingCodex Is Organized
 
 | Layer | What it does | What it does not do |
 | --- | --- | --- |
-| **Native Codex task** | Interprets the request, runs Head Manager, and dynamically dispatches exact fixed-role specialists. | It does not turn ordinary prose into an order or use a generic agent to imitate a specialist. |
+| **Native Codex task** | Interprets the request, takes a direct fast path when sufficient, and uses specialist profiles or a bounded generic child only when needed. | It does not turn ordinary prose, a child, or a skill into policy, approval, broker, or execution authority. |
 | **Workspace** | Holds readable research, reports, source snapshots, skills, prompts, and lightweight run provenance. | It is not the portfolio, order, account, approval, or secret ledger. |
 | **Django service** | Enforces artifact identity, policy, approval, broker, idempotency, execution, and audit rules through shared application services. | It does not replace Codex with a semantic router, preset team, or stored workflow DAG. |
 | **Read-only viewer** | Lets you browse Library artifacts, Skills, System posture, and registered workspaces. | It does not launch Codex, write workspace files, or mutate orders, brokers, skills, or policy. |
@@ -123,11 +124,11 @@ that state in prompts or workspace files.
 - Fixed roles have bounded tools and handoff responsibilities. A final order
   path is available only from an exact root-native protocol, never from the
   viewer, a subagent, public REST, generic CLI, or direct MCP call.
-- User-installed MCP servers, skills, and plugins are BYOR native Codex
-  capabilities. TradingCodex neither recommends nor verifies them; their
-  licenses, data terms, costs, and side effects remain the user/provider's
-  responsibility, and TradingCodex guarantees cover only its own capabilities,
-  state, and actions.
+- Relevant user-installed MCP servers and skills remain BYOR native Codex
+  capabilities. One relevant capability can be used for evidence without
+  becoming TradingCodex-managed. OpenBB is the one TradingCodex-supported
+  external data integration: it is optional, projected directly to evidence
+  roles, and still subject to upstream licenses and data terms.
 - Raw credentials do not belong in prompts, workspace files, reports, API/MCP
   output, or audit data.
 
@@ -142,6 +143,7 @@ guarantee returns.
 | [User Guide](https://monarchjuno.github.io/tradingcodex/) | Setup, examples, concepts, all user-facing skills, and provider-to-order onboarding. |
 | [Installation](installation.md) | Install variants, updates, runtime homes, MCP/service startup, and recovery. |
 | [User-facing skills](docs/user-facing-skills.md) | The full skill map, entry rules, and hard stops. |
+| [Data sources and OpenBB](docs/data-sources-and-openbb.md) | Source routing, direct optional OpenBB projection, Snapshot/Dataset evidence, and third-party terms. |
 | [Research memory and artifacts](docs/research-memory-and-artifacts.md) | Artifact paths, source posture, versions, quality labels, forecasts, and exports. |
 | [Decision memory](docs/decision-memory.md) | Replay, postmortems, lesson validation, and reusable context. |
 | [Safety policy and execution](docs/safety-policy-and-execution.md) | Permissions, approvals, brokers, secrets, and execution boundaries. |

tradingcodex-1.2.1/docs/README.md

@@ -0,0 +1,102 @@
+# TradingCodex Documentation
+
+`docs/` is the canonical product reference. It explains durable behavior and
+the reasons behind it; it is not a second user guide or a source-file index.
+
+- New users start with the [User Guide](https://monarchjuno.github.io/tradingcodex/).
+- Operators start with [installation.md](../installation.md).
+- Maintainers start with [AGENTS.md](../AGENTS.md) and
+  [openwiki/quickstart.md](../openwiki/quickstart.md), then read the owning page
+  below before changing behavior.
+
+## Documentation Ownership
+
+| Layer | Purpose |
+| --- | --- |
+| `README.md` | Product summary and primary install route. |
+| `installation.md` | Setup, update, and operator recovery. |
+| `docs/` | Canonical product behavior, architecture, safety, and rationale. |
+| `guidebook/` | Short task-first instructions for end users. |
+| `openwiki/` | Source ownership and validation routing for coding agents. |
+| `AGENTS.md` | Repository-wide development rules. |
+
+Keep a concept in one owning document and link to it elsewhere. Update another
+layer only when its audience's route changes; do not copy a behavior contract
+into every layer. If two layers disagree, fix the owning `docs/` page first.
+
+## Start By Goal
+
+| Goal | Canonical page | Useful follow-up |
+| --- | --- | --- |
+| Understand the product and its design posture | [Product Direction](product-direction.md) | [Harness](harness.md) |
+| Understand runtime and source ownership | [System Architecture](system-architecture.md) | [Interfaces And Surfaces](interfaces-and-surfaces.md) |
+| Change Head Manager, roles, skills, or research flow | [Roles, Skills, And Workflows](roles-skills-and-workflows.md) | [Codex-Native Orchestration](codex-native-orchestration.md) |
+| Work with research evidence, datasets, and artifacts | [Research Memory And Artifacts](research-memory-and-artifacts.md) | [Data Sources And OpenBB](data-sources-and-openbb.md) |
+| Work with reusable company, product, technology, science, industry, or value-chain knowledge | [Knowledge Wikis](knowledge-wikis.md) | [Investment Brain Plugins](investment-brain-plugins.md) |
+| Understand saved decisions and improvement | [Decision Memory](decision-memory.md) | [Improvement Loop](improvement-loop.md) |
+| Change policy, approvals, brokers, or execution | [Safety, Policy, And Execution](safety-policy-and-execution.md) | [Guardrails](guardrails.md) |
+| Change attach/update or generated workspace files | [Generated Workspaces](generated-workspaces.md) | [Deployment](deployment.md) |
+| Change the viewer, API, MCP, Admin, or CLI | [Interfaces And Surfaces](interfaces-and-surfaces.md) | [System Architecture](system-architecture.md) |
+| Choose or verify validation | [Validation And Test Plan](validation-and-test-plan.md) | [Release Readiness](release-readiness.md) |
+
+## Reference By Domain
+
+### Product And Research
+
+- [Product Direction](product-direction.md) — product thesis, native-Codex
+  posture, goals, non-goals, defaults, and scope.
+- [Harness](harness.md) — how Codex, services, and workspace files cooperate.
+- [Financial Workflow References](financial-workflow-references.md) — finance
+  workflow evidence and non-expert output requirements.
+- [User-Facing Skills](user-facing-skills.md) — direct skill entrypoints and
+  user-visible responsibilities.
+- [Roles, Skills, And Workflows](roles-skills-and-workflows.md) — agent and
+  skill behavior, research routing, and handoffs.
+- [Codex-Native Orchestration](codex-native-orchestration.md) — the durable run
+  boundary and why Django is not an agent scheduler.
+- [Research Memory And Artifacts](research-memory-and-artifacts.md) — file-native
+  evidence, datasets, calculations, artifacts, and provenance.
+- [Knowledge Wikis](knowledge-wikis.md) — agent-maintained Obsidian-compatible
+  background knowledge, explicit write admission, community packages, and the
+  read-only Viewer.
+- [Data Sources And OpenBB](data-sources-and-openbb.md) — source fallback,
+  optional direct OpenBB MCP, and third-party terms.
+- [Decision Memory](decision-memory.md) and [Improvement Loop](improvement-loop.md)
+  — retained decisions, outcomes, lessons, and review.
+
+### Safety And Architecture
+
+- [Safety, Policy, And Execution](safety-policy-and-execution.md) — canonical
+  sensitive-action, approval, broker, secret, and audit boundary.
+- [Guardrails](guardrails.md) — guidance, enforcement, and information-barrier
+  taxonomy.
+- [System Architecture](system-architecture.md) — runtime planes, central DB,
+  app boundaries, and service ownership.
+- [Interfaces And Surfaces](interfaces-and-surfaces.md) — viewer, Admin, API,
+  MCP, CLI, and generated wrapper boundaries.
+- [Generated Workspaces](generated-workspaces.md) — attach/update, generated
+  files, projection, provenance, and platform rules.
+- [Investment Brain Plugins](investment-brain-plugins.md) — current managed
+  Brain behavior and migration context; native user skills remain the preferred
+  direction for future simplification.
+
+### Operations And Governance
+
+- [Validation And Test Plan](validation-and-test-plan.md) — complete validation
+  matrix; use the smallest relevant subset during iteration.
+- [Release Readiness](release-readiness.md) — reusable release and publication
+  checklist; live status remains in GitHub and PyPI.
+- [Deployment](deployment.md) — packaging, publication, update, and CI policy.
+- [Licensing And Commercialization](licensing-and-commercialization.md) — open
+  source, generated workspace, trademark, and legal-review boundaries.
+
+## Writing Rules
+
+- Document durable behavior, not temporary implementation plans or completed
+  checklists; Git history preserves those.
+- Prefer links to repeated explanations. `openwiki/` should contain paths and
+  checks, not a second architecture narrative.
+- Keep user procedures in `guidebook/`; keep internal source paths out of it.
+- Keep product copy in English unless a reviewed localization layer is added.
+- A behavior change updates its owning page in the same change. A code-only
+  refactor that preserves behavior need not churn every documentation layer.

{tradingcodex-1.1.2 → tradingcodex-1.2.1}/docs/codex-native-orchestration.md

@@ -3,18 +3,18 @@
 Status: v1 contract
 
 TradingCodex uses Codex itself as the investment research orchestrator. Head
-Manager interprets the user's original language, chooses the smallest useful
-fixed-role team, runs independent work in parallel, waits for authenticated
-artifacts, and decides whether to revise, add a role, challenge a conflict,
-stop, or synthesize.
+Manager interprets the user's original language, answers narrow trusted facts
+directly, and uses the smallest useful role set when fresh research or distinct
+expertise is needed. It decides whether to follow up, add a role, challenge a
+conflict, stop, answer directly, or synthesize.
 
 ```text
 User
   -> Head Manager
      -> begin_analysis_run (identity, request hash, sealed Brain/Strategy/Context provenance)
      -> optional one explicit Investment Brain inquiry overlay
-     -> exact fixed-role children
-     -> authenticated research artifacts
+     -> optional role-profile or workflow-defined fallback children
+     -> optional authenticated research artifacts
      -> dynamic next-role judgment
      -> run-local synthesis artifact
 ```
@@ -45,6 +45,13 @@ validated plugin `brain_id`, version, content digest, source metadata, manifest
 and source paths, and projected skill path. It does not store the raw request,
 a selected team, a plan, or a task queue.
 
+Codex owns thread, child, wait, and follow-up lifecycle. TradingCodex does not
+pre-allocate or mirror a Codex session-to-run map. When durable research
+provenance is needed, `begin_analysis_run` creates the run ID and Head Manager
+passes that returned ID in compact child briefs and authenticated artifact
+calls. A follow-up in the same Codex task reuses that ID from task context;
+TradingCodex does not reconstruct it from a session map.
+
 ## Investment Brain Context
 
 The native task may select at most one Primary Brain through one exact
@@ -72,23 +79,30 @@ falsify a Brain or Strategy assumption. Strategy governs a decision-rule
 conflict with Brain, while Investor Context remains blocking when suitability
 conflicts with Strategy.
 
-## Dispatch Contract
-
-Every fixed-role child uses MultiAgent V2 with:
-
-- explicit `features.multi_agent_v2.enabled = true`
-- seven total session threads, preserving six child slots before the
-  TradingCodex reserved-slot policy
-- exact registered `agent_type`
-- compact underscore-only `task_name`
-- compact role-owned assignment containing the analysis run id
-- `fork_turns="none"`
-- the role's projected model, reasoning effort, sandbox, web posture, skills,
-  and MCP principal
-
-Each revision or follow-up is a fresh child. `followup_task`, generic/default
-agent fallback, full-history fork, role-TOML emulation, and source-code routing
-are not valid TradingCodex paths.
+## Delegation Contract
+
+MultiAgent V2 exposes the generated role profiles with a depth-one boundary.
+Head Manager prefers an exact profile when its specialty is useful and passes a
+compact role-owned brief rather than the full root history. Role TOML supplies
+the direct fixed model settings; their values and fallback eligibility are owned
+by [Roles, Skills, And Workflows](roles-skills-and-workflows.md). Role profiles
+retain their projected web posture, skills, tools, and MCP principal.
+
+For an exact profile, Head Manager calls native `spawn_agent` with the exact
+`agent_type`, a compact `message`, a `task_name`, and `fork_turns="none"`. It
+does not pass `model` or `reasoning_effort`. A spawn is real only when the tool
+returns a live target. Correct a rejected spawn only when its error identifies
+the change; otherwise delegation remains blocked.
+
+Use `followup_task` when a live child still owns a correction or clarification.
+Start another child for a new specialty, an unavailable session, or independent
+review. Apply the canonical fallback boundary in
+[Roles, Skills, And Workflows](roles-skills-and-workflows.md). A child cannot
+approve, execute, access a broker, or emulate Head Manager. Children never
+delegate recursively. Head Manager waits only while a live child has useful work
+and reports lifecycle events only from native tool and child-lifecycle results
+in the current run. Native wait is wait-any and may serialize with no explicit
+target list; that representation is not failure by itself.
 
 When a Brain applies, the assignment contains the question Head Manager derived
 from it, not the Brain body or a delegation of Brain authority. Brain content is
@@ -96,7 +110,8 @@ never copied into fixed-role configuration.
 
 ## Artifact And Lineage Contract
 
-Producing roles store their own output through `create_research_artifact`.
+Decision-, reuse-, audit-, or handoff-relevant roles store their own output
+through `create_research_artifact`; a narrow bounded answer need not create one.
 Authenticated service code derives the producer identity and content hash,
 verifies the analysis run, and resolves exact run-local `input_artifact_ids`
 into immutable input hashes. Head Manager reads exact returned artifact IDs
@@ -147,14 +162,20 @@ Brain invocation occur in native Codex tasks.
 
 A passing native smoke proves:
 
-1. hooks provide transport/run context without semantic classification;
-2. Head Manager calls `begin_analysis_run` for a fresh investment request;
+1. hooks provide compact context and proof gates without semantic classification
+   or generic shell-policy duplication;
+2. Head Manager uses the direct fast path or calls `begin_analysis_run` only for
+   fresh research and decision work;
 3. Korean and English requests both route by agent understanding;
-4. exact Sol Head Manager and Terra roles use the configured reasoning levels;
-5. spawns use exact V2 role identity and `fork_turns="none"`;
-6. no Brain preserves baseline behavior, one exact Brain changes only inquiry
+4. generated root TOML inherits the user's model and reasoning settings, while
+   fixed-role TOML applies the child settings defined by the canonical role
+   contract;
+5. exact profiles spawn with compact fresh context, child follow-up targets a
+   returned live child, and lifecycle claims match completed native tool calls;
+6. fallback behavior matches the canonical role contract;
+7. no Brain preserves baseline behavior, one exact Brain changes only inquiry
    and interpretation, and multiple or unresolved Brains fail closed;
-7. artifacts are principal-bound and preserve run-local Brain and input lineage;
-8. Head Manager dynamically revises from artifacts without old plan tools;
-9. memory-influenced judgment is blind-first and reports its delta; and
-10. order/approval/execution gates remain service-owned.
+8. artifacts are principal-bound and preserve run-local Brain and input lineage;
+9. Head Manager dynamically revises from artifacts without old plan tools;
+10. memory-influenced judgment is blind-first and reports its delta; and
+11. order/approval/execution gates remain service-owned.

tradingcodex-1.2.1/docs/data-sources-and-openbb.md

@@ -0,0 +1,131 @@
+# Data Sources And OpenBB
+
+This page is the canonical contract for external research sources. It does not
+cover broker connectivity or execution; see
+[safety-policy-and-execution.md](./safety-policy-and-execution.md) for those
+boundaries.
+
+## Source routing
+
+The shared `tcx-source-gate` skill gives an evidence-producing role this order
+for each missing fact or series:
+
+1. Reuse a relevant SourceSnapshot or Dataset already supplied for the work.
+2. Use one relevant enabled user Skill, Plugin, or MCP capability.
+3. Use the optional direct OpenBB MCP if it is projected for the role.
+4. Research original public records: company IR and filings for companies,
+   exchanges for prices, central banks or statistics agencies for macro data,
+   and regulators for regulatory facts.
+5. Use another reliable web source.
+6. State the remaining data gap.
+
+This is a short operating procedure, not a service-side source-rating system or
+a guarantee about a third party. A role names the provider where possible, does
+not repeat an unchanged request to the same source, and keeps a partial result
+while asking the next source only for the missing field, identifier, or period.
+TradingCodex does not install, classify, proxy, approve, or audit a user-owned
+capability. The normal research safety boundaries still apply: never expose a
+secret or mix research retrieval with account, order, or other mutation work.
+Generic web, browser, and shell HTTP access belong to the public-web fallback;
+they are not the user capability in step 2. For structured prices, OHLCV,
+fundamentals, estimates, or macro series, an available direct OpenBB route is
+attempted before that fallback unless the user selected another provider.
+
+Evidence is fit to a claim and intended use rather than accepted or rejected by
+provider class. Original public records remain preferred when a claim requires
+source-of-record authority, but attributable non-primary evidence may support
+the fields and periods it actually covers. Missing or ambiguous coverage limits
+only dependent claims and actions; it does not erase independent valid fields
+or prevent factual and screen-grade research. This preserves the distinction
+between evidence usability and decision or execution readiness without adding
+a provider trust score, allowlist, or routing registry.
+
+Freshness is relative to the requested as-of, the source's observation or
+publication cadence, the relevant instrument or venue session, and the claim.
+The latest completed period may be the current usable anchor before another
+period exists. Offset-free provider timestamps remain explicitly ambiguous and
+epoch values are converted once; neither is repaired by inventing a timezone.
+A material missing slice that remains obtainable is fetched from the next
+relevant source or returned to its live owner before an evidence-gap abstention.
+
+The procedure adds point-in-time context only when structured or historical
+evidence matters to a conclusion. It preserves issuer identity and
+instrument/venue, unit/currency/timezone, raw-versus-adjusted price policy,
+filing timing/period/amendment posture, and macro first-release or vintage
+posture versus a current revision. It also makes as-of/known-at/freshness,
+empty/partial/stale/authentication/entitlement/rate-limit warnings, material
+conflicts, and remaining coverage gaps visible. Narrow facts do not carry a
+full evidence checklist.
+
+## Evidence records
+
+Every used external document or response is recorded as a content-addressed
+`SourceSnapshot`. Its provider, locator, as-of and known-at posture, hashes,
+warnings, and necessary excerpt preserve provenance for filings, news, IR
+material, HTML/PDF extracts, and other unstructured sources.
+
+A `Dataset` is optional. Create one only when a reusable table, time series,
+OHLCV set, or financial table is used. Preserve every row used in the analysis;
+the immutable Dataset manifest binds its payload and source snapshots. A
+`ResearchArtifact` cites the exact SourceSnapshot and Dataset IDs it consumed.
+The resulting flow is:
+
+```text
+external source → SourceSnapshot → Dataset (only for reusable structured rows) → ResearchArtifact
+```
+
+There is no separate external-call receipt state machine and no document-blob
+store. Existing Snapshot payload/locator/hash data and a necessary excerpt are
+the current retention boundary. Add a source-specific adapter only when a real,
+repeatable pipeline requires one; TradingCodex does not own adapters for SEC,
+Treasury, BLS, ECB, World Bank, CFTC, Bank of Canada, or similar sources.
+
+## Optional OpenBB MCP
+
+OpenBB is enabled by default as an optional, non-required source and is not
+installed or started by `tcx attach` or `tcx update`. Generated configuration
+projects the official upstream MCP directly to fundamental, technical, news,
+macro, instrument, and valuation roles only. Head Manager, portfolio, risk,
+and judgment roles do not receive it. An explicit `disable` choice is preserved
+by later workspace updates.
+
+```toml
+[mcp_servers.openbb]
+command = "uvx"
+args = ["--from", "openbb-mcp-server", "--with", "openbb", "openbb-mcp", "--transport", "stdio"]
+enabled = true
+required = false
+env_vars = ["FMP_API_KEY"]
+```
+
+`uvx` resolves the upstream packages only when Codex actually uses the MCP.
+TradingCodex never wraps, provisions, supervises, validates, or proxies that
+server. The configuration stores environment-variable *names* only; values are
+inherited from the process that starts Codex and must not appear in workspace
+files, prompts, APIs, MCP output, artifacts, or logs.
+
+Only a role that actually selects this direct route reads the short OpenBB
+procedure. It discovers the smallest needed upstream route, names and verifies
+the provider when available, verifies returned identifiers/venue/time posture
+and data units or adjustments, and treats access or empty-result warnings as
+coverage gaps. A partial response remains usable while another source fills
+only the missing coverage. Used responses become SourceSnapshots immediately;
+reused structured rows also become Datasets. The procedure deliberately avoids
+tool-name or version coupling.
+
+From a workspace terminal, use only the small projection controls:
+
+```bash
+./tcx data-sources openbb status
+./tcx data-sources openbb env add OTHER_PROVIDER_KEY
+./tcx data-sources openbb disable
+./tcx data-sources openbb enable --env-var FMP_API_KEY
+./tcx update --skip-refresh --no-doctor
+```
+
+Restart Codex after changing the projection or inherited environment. OpenBB,
+its providers, and their data remain third-party services: package licensing,
+provider terms, entitlement, cost, availability, accuracy, and data-use duties
+are the user's responsibility. In particular, optional direct use does not by
+itself settle OpenBB AGPL or downstream data-license obligations. See the
+[upstream OpenBB license guidance](https://docs.openbb.co/odp/python/faqs/license).

{tradingcodex-1.1.2 → tradingcodex-1.2.1}/docs/decision-memory.md

@@ -120,6 +120,11 @@ does not establish truth.
 
 ### Wiki and graph posture
 
+This section describes rebuildable views over Decision Memory. It does not own
+the separate agent-maintained background vault defined by
+[Knowledge Wikis](knowledge-wikis.md). Knowledge Wiki pages never become the
+canonical decision ledger or gain automatic promotion from it.
+
 LLM-maintained Markdown is useful for navigation, synthesis, and progressive
 disclosure. It is unsuitable as the only investment memory because free-form
 pages do not reliably preserve observation time, contradicted claims, abandoned
@@ -364,13 +369,13 @@ Memory remains independent of the Brain that produced a decision:
 - a different Brain or Strategy starts a new run rather than mutating sealed
   provenance.
 
-Learning from memory into a Brain is a separate user-controlled curation path.
-Writing requires a root native Codex prompt whose first meaningful invocation
-is `$tcx-brain`, an explicit source-authoring request on that line or below it, an
-actual Codex sandbox that permits the required workspace-local writes, exact
-user-selected source episodes, and counterexamples. The Brain-scoped grant is
-bound to that turn, cannot authorize Build or Strategy work, and does not carry
-into follow-ups or subagents; the browser viewer has no management path.
+Learning from memory or a selected Wiki page into a Brain is a separate
+user-controlled curation path. Natural language may explicitly authorize a
+user-owned source revision and proof-free validation; it does not authorize a
+managed lifecycle change. Exact `$tcx-brain` first-line admission is required
+only for install, update, activation, deactivation, rollback, or removal. The
+Brain lifecycle grant cannot authorize Build, Wiki, or Strategy work and does
+not carry into follow-ups or subagents; the browser viewer has no mutation path.
 It abstracts general heuristics into a privacy-reviewed user-owned local source
 without copying private cases or changing Decision Memory, installed packages,
 or third-party sources. It validates a created or revised local source without