---
title: FAQ
description: Frequently asked questions based on recurring docs feedback themes.
---

# FAQ

This FAQ is sourced from recurring themes in docs feedback submissions and docs-related support questions.

- Browse docs issues: [Documentation issues](https://github.com/hypertrial/stacksats/issues?q=is%3Aissue+label%3Adocumentation)
- Submit new feedback: [Docs feedback template](https://github.com/hypertrial/stacksats/issues/new?template=docs_feedback.md)

## Strategy authoring

### Which hook should I implement: `propose_weight` or `build_target_profile`?

Use `propose_weight(state)` for day-by-day logic. Use `build_target_profile(...)` for vectorized, window-level logic.

See: [Minimal Strategy Examples](start/minimal-strategy-examples.md).

### Do I need to implement both hooks?

No. Implement one intent path. The framework will enforce the same allocation invariants either way.

### Why can’t I override `compute_weights` directly?

`compute_weights` is framework-owned and sealed to preserve invariant safety, lock semantics, and consistent runtime behavior.

See: [Framework Boundary](framework.md).

## CLI and outputs

### What is the recommended production flow: `decide-daily` or `run-daily`?

Use `decide-daily` when StackSats should emit a validated, execution-ready decision payload for an external AI agent or brokerage workflow.
Use `run-daily` only when you intentionally want StackSats to submit through a configured execution adapter after generating that same decision.

### Where are artifacts written?

Backtest and export artifacts are written under:

`output/<strategy_id>/<version>/<run_id>/`

See: [CLI Commands](commands.md).

### Why does export require `--start-date` and `--end-date`?

Export requires explicit date bounds to avoid accidental implicit ranges and to make outputs reproducible.

### What files should I expect after a run?

Common files:

- backtest: `backtest_result.json`, `metrics.json`, plot `.svg` files
- export: `weights.csv`, `timeseries_schema.md`, `artifacts.json`

See: [Backtest Runtime](model_backtest.md) and [WeightTimeSeries](reference/strategy-timeseries.md).

## Migration and compatibility

### My code used `compute_weights_shared` or a hardcoded backtest end. What do I use now?

Use explicit replacements from [Migration Guide](migration.md):

- `compute_weights_shared(...)` -> `compute_weights_with_features(..., features_df=...)`
- backtest end constant/override -> `get_backtest_end()` (canonical default is `2025-12-31`)

### My code used `model_development.softmax` or `strategy.export_weights(...)`. What now?

Both compatibility APIs were removed:

- `stacksats.model_development.softmax(...)` -> `stacksats.model_development_helpers.softmax(...)`
- `BaseStrategy.export_weights(...)` -> `BaseStrategy.export(...)`

See: [Migration Guide](migration.md).

### Did `load_data(...)` behavior change?

Yes. `stacksats.load_data(...)` now follows strict `BTCDataProvider` source-only semantics:

- no synthetic "today" row
- no historical gap filling
- no MVRV fallback substitution
- feature warmup history is retained by default (rows before `backtest_start` are included for feature computation)

The canonical source dataset is long-format `merged_metrics*.parquet` (see [Merged Metrics Parquet Schema](reference/merged-metrics-parquet-schema.md) and [BRK Data Source](data-source.md)). Runtime commands read a derived BRK-wide parquet via `STACKSATS_ANALYTICS_PARQUET`, the managed default under `~/.stacksats/data/bitcoin_analytics.parquet`, or the legacy local fallback `./bitcoin_analytics.parquet`; for custom DataFrames use `StrategyRunner.from_dataframe(df, column_map=...)` or `ColumnMapDataProvider`. Treat the DataFrame path as an advanced integration option, not the default first-run workflow. Use `end_date=...` when you need an explicit end bound.

If you need a lazy integration point before the final execution boundary, use `BTCDataProvider.load_lazy(...)` or `ColumnMapDataProvider.load_lazy(...)`. Strategy hooks themselves still receive eager `pl.DataFrame` inputs.

### Which modules are stable public API?

Use top-level `stacksats` exports, documented artifact payloads, and the documented CLI subset. Generated module pages are reference material, not a promise that the module import path is stable.

For canonical `merged_metrics*.parquet` exploration, use the stable public
top-level exports `open_merged_metrics()` and `load_metric_catalog()` plus [EDA Quickstart](start/eda-quickstart.md).

See: [API Reference](reference/api/index.md) and [Stability Policy](stability.md).

### Are `stacksats-plot-mvrv` and `stacksats-plot-weights` part of the stable CLI?

No. They are documented helper console scripts for plotting workflows, but the frozen stable `1.x` CLI contract is the `stacksats demo`, `stacksats data`, and `stacksats strategy` subtree documented in the stability policy.

Treat the helper scripts as convenience entry points with optional extras:

- `stacksats-plot-mvrv` requires `stacksats[viz]`
- `stacksats-plot-weights` requires both `stacksats[viz]` and `stacksats[deploy]`

## Docs feedback workflow

### How is this FAQ updated?

Maintainers periodically review docs feedback issues and fold recurring questions into this page.

### How should I report a docs gap?

Open an issue using the docs feedback template and include:

- page URL
- what you were trying to do
- what was unclear
- suggested improvement

## Feedback

- [Was this page helpful? Open docs feedback issue](https://github.com/hypertrial/stacksats/issues/new?template=docs_feedback.md&title=%5Bdocs%5D+Feedback%3A+FAQ)
