/sap-docs-layout

name: sap-docs-layout
description: |
  Edits the structural layout of a SAP design spec template (.xlsx) by writing
  to the workbook's `(Meta) Layout` sheet. Lets customers customize sheet
  names, column orders, and output mappings without editing Markdown rules or
  skill code. The meta sheet becomes the per-workbook source of truth that
  `/sap-docs-extract` reads on its next run.

  Operations:
    inspect       Print the current layout in human-readable form.
    bootstrap     Copy a `(Meta) Layout` sheet from the canonical
                  `spec_template.xlsx` into a workbook that doesn't have one.
    add-column    Add a column to a section. Updates xlsx + meta in one step.
    rename-sheet  Rename a sheet and update meta so the parser still finds it.
    validate      Reconcile the meta sheet against actual workbook structure.

  Input: workbook path + operation + op-specific args.
  Output: in-place modifications to the .xlsx file. A timestamped backup is
  written next to the original before any write operation.
argument-hint: "<operation>  [<workbook-path>]  [op-specific-flags]"

SAP Docs Layout Skill

You edit the structural layout of a customer's design-spec template. Customers fill specs into `spec_template.xlsx`; this skill is what they use to customize that template's structure without touching Markdown rules or Python.

The skill writes to a hidden `(Meta) Layout` sheet inside the workbook. That sheet is the **only** authoritative description of the workbook's layout. `/sap-docs-extract` reads it directly. The canonical `spec_template.xlsx` ships with a populated Meta sheet; `bootstrap` copies it into other workbooks when needed.

Task: $ARGUMENTS

Shared Resources

| File | Purpose | |---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | Mandatory operating rules | | `<SAP_DEV_CORE_SHARED_DIR>/rules/ddic_excel_layout_rules.md` | DDIC Excel-spec authoring rules — naming-suffix consistency, primitive-type-as-DTEL trap, currency reference, column order, no merged data cells. Constrain meta-layout edits to remain compatible with the rule set. | | `<SAP_DEV_CORE_SHARED_DIR>/rules/language_independence_rules.md` | GUI-scripting language independence — offline layout editor, but rule applies to downstream deploy skills the spec feeds | | `<SKILL_DIR>/templates/spec_layout_schema.md` | Canonical schema for the `(Meta) Layout` sheet. Read this before generating or editing meta rows. | | `<SAP_DEV_CORE_SHARED_DIR>/templates/spec_template.xlsx` | Canonical reference template. Default target when no workbook path is provided. `bootstrap` copies its `(Meta) Layout` sheet into other workbooks. | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_log_helper.ps1` | Structured logging. | | `<SKILL_DIR>/references/edit_meta_layout.py` | openpyxl helper — read/write meta sheet, perform structural edits, copy Meta sheet between workbooks. |

---

Step 0 — Resolve Work Directory

**Resolve `work_dir` via the env-aware helper** — do NOT take `work_dir` from a direct `settings.json` read (that ignores the `SAPDEV_AI_WORK_DIR` env var and `userconfig.json`). Use the `WORK_DIR=` value printed by:

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_settings_lib.ps1'; . '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('WORK_DIR=' + (Get-SapWorkDir)); Write-Output ('RUN_TEMP=' + (Get-SapRunTemp))"

The settings note below still applies to the OTHER keys.

**Settings reads/writes follow `<SAP_DEV_CORE_SHARED_DIR>/rules/settings_lookup.md`** — merge per-key on the `.value` field (env var → `settings.local.json` → `userconfig.json` → `settings.json`); non-per-connection writes go to `userconfig.json`. Resolve cross-plugin paths: 3 levels up from `<SKILL_DIR>`, then `sap-dev-core/settings.json` and (if present) `sap-dev-core/settings.local.json`. Read `custom_url`.

| Setting | Default if blank | |---|---| | `work_dir` | `C:\sap_dev_work` | | `custom_url` | `{work_dir}\custom` |

Set `{WORK_TEMP}` = `{work_dir}\temp`. Ensure it exists. Set `{RUN_TEMP}` = the `RUN_TEMP=` value printed above (`Get-SapRunTemp` mints + creates a fresh per-run dir `{work_dir}\temp\run_<id>`) — the per-run scratch dir holding the log state file. Mint it once here and reuse the same value in Step 0.5 and Final — do not call `Get-SapRunTemp` again later.

---

Step 0.5 — Start Logging

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_docs_layout_run.json" -Skill sap-docs-layout -ParamsJson "{\"args\":\"<RAW_ARGUMENTS>\"}"

---

Step 1 — Parse Operation and Workbook Path

Tokenise `$ARGUMENTS`. The first positional argument MUST be one of:

inspect | bootstrap | add-column | rename-sheet | validate

If the first token is none of those, the user spoke conversationally ("add an AuthGroup column to my Field Definitions sheet") — translate into the explicit form yourself, confirm with the user, and proceed.

The second positional argument is the **workbook path**. If omitted:

1. If `{custom_url}\spec_template.xlsx` exists → use it. 2. Else fall back to `<SAP_DEV_CORE_SHARED_DIR>\templates\spec_template.xlsx`.

Report the chosen path:

INFO: Workbook: <resolved-path>
INFO: Operation: <op>

If the resolved workbook does not exist, abort with:

ERROR: Workbook not found at <path>. Pass the path explicitly:
  /sap-docs-layout <op> C:\path\to\template.xlsx ...

Op-specific flags follow the workbook path. They are documented per operation in Steps 3a–3e below.

---

Step 2 — Backup the Workbook (skip for `inspect` and `validate`)

Read-only operations (`inspect`, `validate`) never modify the file — skip this step for them.

For all other operations, before any write:

from datetime import datetime
import shutil
from pathlib import Path

src = Path(workbook_path)
ts = datetime.now().strfti