4 add examples in facades section

.codex/SKILLS.md

@@ -0,0 +1,40 @@
+# Local Codex Skills
+
+This repository now uses small, task-focused skills instead of one monolithic skill document.
+
+## Skills
+
+- `pdf-operations`
+  - Purpose: Aspose.PDF operation patterns, API hints, and example behavior rules.
+  - File: `.codex/skills/pdf-operations/SKILL.md`
+- `code-style`
+  - Purpose: Shared formatting, file layout, naming, path, and error-handling conventions.
+  - File: `.codex/skills/code-style/SKILL.md`
+- `spec-generator`
+  - Purpose: Generate or refresh machine-readable example specs and scaffold new example files.
+  - File: `.codex/skills/spec-generator/SKILL.md`
+
+## Suggested Combinations
+
+- New example implementation:
+  - `pdf-operations` + `code-style`
+- Refactor or normalize an existing example:
+  - `pdf-operations` + `code-style`
+- Refresh generated repository metadata/specs:
+  - `spec-generator`
+- Add a new example and keep generated specs in sync:
+  - `pdf-operations` + `code-style` + `spec-generator`
+
+## Scripts
+
+- `python scripts/generate_example_specs.py`
+  - Scans `examples/` and refreshes generated spec artifacts under `specs/examples/`
+- `python scripts/generate_example_stub.py --category <category> --name <slug> --operation <function_name>`
+  - Scaffolds a new example file using the repo's standard template
+
+## Generated Artifacts
+
+- `specs/examples/index.json`
+- `specs/examples/index.md`
+
+Treat those files as generated outputs. Re-run the generator after adding or materially changing example modules.

.codex/config.yaml

@@ -0,0 +1,29 @@
+# ~/.codex/config.yaml
+
+# --- Core Codex Settings ---
+model: gpt-5.3
+approval_mode: auto-edit
+notify: true
+
+# --- Execution Behavior ---
+fullAutoErrorMode: ask-user   # ask-user | ignore-and-continue
+
+# --- Project Instructions ---
+instructions: |
+  You are working in a repository of Python examples for Aspose.PDF for Python via .NET.
+
+  Prefer the narrowest applicable local skill from `.codex/skills/`:
+  - `pdf-operations` for Aspose.PDF API usage and example behavior
+  - `code-style` for structure, naming, path handling, and output conventions
+  - `spec-generator` for generating or refreshing repository example specs
+
+  Global repository rules:
+  - Preserve the established example architecture under `examples/`
+  - Reuse `examples/config.py` for `set_license(...)` and `initialize_data_dir(...)`
+  - Do not add new dependencies beyond the repo's current Python requirements unless explicitly requested
+  - Prefer repo-owned automation in `scripts/` over ad-hoc one-off generation logic
+  - When examples are added or materially changed, refresh the generated spec artifacts with:
+    `python scripts/generate_example_specs.py`
+  - When scaffolding a new example, prefer:
+    `python scripts/generate_example_stub.py --category <category> --name <slug> --operation <function_name>`
+  - Keep generated artifacts deterministic and safe to re-run

.codex/skills/code-style/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: code-style
+description: Apply shared repository style rules for Aspose.PDF Python example files, including structure, naming, path handling, docstrings, status output, and error handling.
+metadata:
+  short-description: Shared style rules for example scripts
+  version: "1.0"
+---
+
+# Code Style
+
+## Use This Skill When
+
+- Creating or refactoring repository example scripts
+- Normalizing older examples to the current house style
+- Reviewing whether generated code matches repository conventions
+
+## Structure Rules
+
+- Keep the import block simple and consistent
+- Always use:
+  - `from os import path`
+  - `sys.path.append(path.join(path.dirname(__file__), '..'))`
+- Use following snippet in `facades` subfolder examples:
+  ```python
+  from os import path
+  import sys
+
+  CURRENT_DIR = path.dirname(__file__)
+  EXAMPLES_DIR = path.abspath(path.join(CURRENT_DIR, "..", ".."))
+  if EXAMPLES_DIR not in sys.path:
+    sys.path.insert(0, EXAMPLES_DIR)
+  ```
+- Import shared helpers from `examples/config.py`
+- Preserve `run_all_examples()` as the entrypoint
+
+## Function Rules
+
+- Operation functions must accept file paths as `str`
+- Do not pass `Document` objects between functions
+- Use descriptive names tied to the actual action
+- Keep one function responsible for one operation
+
+## Path Rules
+
+- Use `path.join(...)` for repository-local paths
+- Do not hardcode absolute paths
+- Use `initialize_data_dir(...)` instead of hand-rolling sample-data locations
+
+## Error Handling And Output
+
+- Wrap each example run in `try/except`
+- Do not stop the full example run because one case failed
+- Preserve the repository's success/failure markers:
+  - `✅ Success`
+  - `❌ Failed`
+
+## Documentation
+
+- Add or preserve concise docstrings on public example functions
+- Prefer docstrings with `Args` and `Returns` when the function is non-trivial
+- Keep comments brief and useful
+
+## Anti-Patterns
+
+- Hardcoded file system paths
+- Breaking `run_all_examples()`
+- Removing status prints
+- Adding dependencies not already used by the repo
+- Large architectural rewrites for narrow example changes

.codex/skills/pdf-operations/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: pdf-operations
+description: Implement or update Aspose.PDF for Python via .NET example logic, including opening, saving, merging, splitting, protecting, converting, and related document operations.
+metadata:
+  short-description: Aspose.PDF example operation guidance
+  version: "1.0"
+---
+
+# PDF Operations
+
+## Use This Skill When
+
+- Creating a new example script for a PDF feature
+- Updating example logic that touches Aspose.PDF APIs
+- Translating a request like merge, split, encrypt, convert, annotate, extract, or optimize into repository code
+
+## Required Behavior
+
+- Operate on file paths, not shared `Document` objects passed between functions
+- Keep one public operation function focused on one concrete behavior
+- Preserve `run_all_examples()` as the execution entrypoint
+- Keep examples runnable in evaluation mode when no license is supplied
+
+## Standard Structure
+
+Every example should align with this flow:
+
+1. Import `aspose.pdf as ap`
+2. Append the parent examples directory with:
+   `sys.path.append(path.join(path.dirname(__file__), '..'))`
+3. Import `set_license` and `initialize_data_dir` from `config`
+4. Implement one or more operation functions accepting string paths
+5. Implement `run_all_examples(data_dir=None, license_path=None)`
+6. Call `set_license(...)` and `initialize_data_dir(...)`
+7. Execute examples with per-example `try/except`
+
+For nested example folders, adjust the shared-config import path to match the real directory depth. For example, files under `examples/facades/pdf_content_editor/` can use:
+
+```python
+CURRENT_DIR = path.dirname(__file__)
+EXAMPLES_DIR = path.abspath(path.join(CURRENT_DIR, "..", ".."))
+if EXAMPLES_DIR not in sys.path:
+    sys.path.insert(0, EXAMPLES_DIR)
+
+from config import set_license, initialize_data_dir
+```
+
+## API Reference
+
+- Open document:
+  - `ap.Document(path)`
+  - `ap.Document(path, password)`
+- Save document:
+  - `document.save(path)`
+- Merge:
+  - `doc1.pages.add(doc2.pages)`
+- Encrypt:
+  - `document.encrypt(user_pwd, owner_pwd, privileges, algorithm, False)`
+- Convert:
+  - `document.convert(log_path, ap.PdfFormat.PDF_X_3, ap.ConvertErrorAction.DELETE)`
+
+## Facades
+
+Use facade APIs when the repository already demonstrates a task through `aspose.pdf.facades` rather than the core `Document` API. In these examples, the operation function should still accept file paths, but the implementation can create and bind a facade object internally.
+
+### Shared Facade Pattern
+
+For content-editor style examples:
+
+```python
+import aspose.pdf.facades as pdf_facades
+import aspose.pydrawing as apd
+
+def operation_name(infile, outfile):
+    content_editor = pdf_facades.PdfContentEditor()
+    content_editor.bind_pdf(infile)
+    # perform facade operation
+    content_editor.save(outfile)
+```
+
+### Facade Rules
+
+- Keep facade object creation inside the operation function
+- Bind with `bind_pdf(infile)` before mutating content
+- Save with the facade object after the operation is complete
+- Use `aspose.pydrawing` geometry and colors when the facade API requires rectangles or color values
+- Preserve one function per concrete operation even when multiple operations share the same facade class
+
+### PdfContentEditor Examples
+
+Text annotation:
+
+```python
+def add_text_annotation(infile, outfile):
+    content_editor = pdf_facades.PdfContentEditor()
+    content_editor.bind_pdf(infile)
+    content_editor.create_text(
+        apd.Rectangle(100, 400, 50, 50),
+        "Text Annotation",
+        "This is a text annotation",
+        True,
+        "Insert",
+        1,
+    )
+    content_editor.save(outfile)
+```
+
+Free text annotation:
+
+```python
+def add_free_text_annotation(infile, outfile):
+    content_editor = pdf_facades.PdfContentEditor()
+    content_editor.bind_pdf(infile)
+    content_editor.create_free_text(
+        apd.Rectangle(200, 480, 150, 25),
+        "This is a free text annotation",
+        1,
+    )
+    content_editor.save(outfile)
+```
+
+Caret annotation:
+
+```python
+def add_caret_annotation(infile, outfile):
+    content_editor = pdf_facades.PdfContentEditor()
+    content_editor.bind_pdf(infile)
+    content_editor.create_caret(
+        1,
+        apd.Rectangle(350, 400, 10, 10),
+        apd.Rectangle(300, 380, 115, 15),
+        "P",
+        "This is a caret annotation",
+        apd.Color.red,
+    )
+    content_editor.save(outfile)
+```
+
+Markup annotation variants:
+
+```python
+def add_markup_annotation(infile, outfile):
+    content_editor = pdf_facades.PdfContentEditor()
+    content_editor.bind_pdf(infile)
+    content_editor.create_markup(
+        apd.Rectangle(120, 440, 200, 20),
+        "This is a highlight annotation",
+        0,
+        1,
+        apd.Color.yellow,
+    )
+    content_editor.create_markup(
+        apd.Rectangle(110, 542, 200, 20),
+        "This is a underline annotation",
+        1,
+        1,
+        apd.Color.yellow,
+    )
+    content_editor.save(outfile)
+```
+
+Popup annotation:
+
+```python
+def add_popup_annotation(infile, outfile):
+    content_editor = pdf_facades.PdfContentEditor()
+    content_editor.bind_pdf(infile)
+    content_editor.create_popup(
+        apd.Rectangle(220, 520, 180, 80),
+        "This is a popup annotation",
+        True,
+        1,
+    )
+    content_editor.save(outfile)
+```
+
+### When To Prefer Facades
+
+- The existing repo examples for that feature already use `aspose.pdf.facades`
+- The API is centered on editor-style helpers such as content editing, file security, file info, or signatures
+- The operation is naturally modeled as bind -> mutate -> save rather than load `Document` -> traverse object model -> save
+
+## Repository Constraints
+
+- Python 3.7+ source style
+- Allowed dependencies are limited to the repo requirements
+- Do not introduce a test framework just for examples
+- Do not redesign folder structure when a focused example change will do
+
+## Output Expectations
+
+- Generated output names should remain descriptive and stable
+- Prefer `{function_name}_out.pdf` when producing a single canonical PDF output
+- Status lines should remain easy to scan from the console

.codex/skills/spec-generator/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: spec-generator
+description: Generate and maintain repository example specs and example scaffolding artifacts for Aspose.PDF for Python via .NET.
+metadata:
+  short-description: Example spec generation workflow
+  version: "1.0"
+---
+
+# Spec Generator
+
+## Use This Skill When
+
+- Refreshing machine-readable metadata for the example catalog
+- Generating repo documentation from the current `examples/` tree
+- Scaffolding a new example file with the standard repository template
+- Keeping Codex-facing specs aligned with the actual source tree
+
+## Pipeline Entry Points
+
+- Refresh generated specs:
+  - `python scripts/generate_example_specs.py`
+- Scaffold a new example:
+  - `python scripts/generate_example_stub.py --category <category> --name <slug> --operation <function_name>`
+
+## Generated Outputs
+
+- `specs/examples/index.json`
+- `specs/examples/index.md`
+
+These artifacts should be deterministic so they can be regenerated after source changes.
+
+## Generator Expectations
+
+- Scan `examples/` recursively
+- Ignore generated caches and `examples/config.py`
+- Extract stable metadata from Python source
+- Preserve sorted output for low-noise diffs
+- Fail loudly on invalid Python modules instead of silently producing partial garbage
+
+## Integration Rules
+
+- After adding or materially changing an example module, refresh specs before closing the task
+- Prefer updating generator scripts instead of hand-editing generated spec artifacts
+- Keep scaffolded examples aligned with the `pdf-operations` and `code-style` skills

.gitignore

@@ -250,3 +250,4 @@ BundleArtifacts/
 .cake/*
 
 .nugetapikey
+.vscode