docs: document calculated field params dictionary & restore Starlark docs changes

[nrichers]

Pull Request Description

What and why?

This PR adds a Params dictionary reference table to site/guide/inventory/_field-types.qmd, which is included on both Manage inventory fields and Manage artifact fields.

The table documents built-in params keys, including params["model_stage"] for inventory record formulas, along with params["stakeholders"], params["integrations"], params["finding_type"], and params["model"].

Context: While investigating sc-15239, I realized that:

• Our calculated fields documentation did not describe the built-in params dictionary at all, only that formulas read selected field keys. So we weren't missing just model_stage info, we were missing all the params ...
• The Starlark calculated-fields docs from #1323 had been accidentally regressed on main by #1328, which squash-merged a stale copy of _field-types.qmd. This PR restores that docs: Calculated fields formula reference #1323 content and places the params dictionary immediately above the available helpers section.

I did not add worked examples in this PR, ran out of time, but the reference tables should unblock the core documentation gap for sc-15239.

How to test

After the PR preview deploys, spot-check:

• Manage inventory fields — Params dictionary
• Manage inventory fields — Available helpers
• Manage artifact fields — Params dictionary
• Manage artifact fields — Available helpers

Confirm the Calculation section order is: Starlark intro → Params dictionary → Available helpers → setup steps/examples.

Local: quarto render guide/inventory/manage-inventory-fields.qmd guide/validation/manage-artifact-fields.qmd --profile development from site/.

What needs special review?

• Wording and completeness of the params table — especially whether params["integrations"] and params["stakeholders"] descriptions are accurate enough without examples.
• That restoring the docs: Calculated fields formula reference #1323 Calculation block correctly fixes the docs: Models > Records — Developer portal, quickstarts, & training #1328 regression without unintended side effects elsewhere in _field-types.qmd.
• Placement inside the shared _field-types.qmd include (affects both inventory and artifact field guides).

Dependencies, breaking changes, and deployment notes

• Depends on nothing.
• No breaking changes.
• Standard docs deployment only.
• Re-applies calculated-fields content originally merged in docs: Calculated fields formula reference #1323.

Release notes

Documentation now includes a reference table for built-in calculated field params keys, including model stage, and restores the Starlark formula helpers reference. Learn more ...

Checklist

• What and why
• Screenshots or videos (Frontend)
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut
• Unit tests added (Backend)
• Tested locally
• Documentation updated (if required)
• Environment variable additions/changes documented (if required)

[validbeck]

Can you shift the instructions to BEFORE the giant dictionaries? I think it makes more sense that way; I'm approving this otherwise but please don't merge until you make that change?

I think the params / available helpers being in a tabset would also help the sheer amount of text we have in this section as well — if you don't want to do it please leave this PR open so I can adjust?

[github-actions]

PR Summary

This PR updates the documentation for calculated fields in the inventory guide by migrating code examples and explanatory text from a Python dot notation style to the new Starlark dictionary-access style. The key changes include:

• Refining the description of the formula(params) function to emphasize reading field values via dictionary keys (e.g., params["fieldKey"]), which aligns with the Starlark syntax.
• Updating example formulas (e.g., risk tier, severity and due date calculations) to use dictionary-style access rather than attribute access, improving clarity and consistency.
• Adding a dedicated callout section that explains the migration of legacy Python formulas to the Starlark engine and sets the requirement of using Starlark syntax for new formulas.
• Introducing a detailed panel section that documents the built-in keys available in the params dictionary and lists helper functions for handling dates, numbers, and lists, ensuring developers are aware of the available resources when writing their formulas.
• Modifying instructions and inline comments to consistently reflect the new usage patterns for both inventory records and artifacts, including proper references such as params["model"] and params["finding_type"].

Overall, these modifications enhance the clarity of the documentation and assist developers in adapting to the new Starlark-based formula system.

Test Suggestions

• Render the updated documentation in multiple browsers to ensure the new callout and panel sections display correctly.
• Validate that the embedded code examples compile and run in the Starlark engine during interactive testing.
• Review the examples in a live environment to confirm that using dictionary-style access (e.g., params["fieldKey"]) functions as documented.
• Cross-check that legacy Python examples have been clearly marked and that developers understand the transition to Starlark.

[nrichers]

Can you shift the instructions to BEFORE the giant dictionaries? I think it makes more sense that way; I'm approving this otherwise but please don't merge until you make that change?

I think the params / available helpers being in a tabset would also help the sheer amount of text we have in this section as well — if you don't want to do it please leave this PR open so I can adjust?

Yes, that totally makes sense. Here's how the content now appears after b8fb6d7 (it would be nice to also shift the examples, but that would break single sourcing):

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview