improved version of documentation

Author: napetrov

.github/instructions/cython.instructions.md

@@ -5,241 +5,21 @@ applyTo:
   - "dpctl/**/*.pxi"
 ---
 
-# Cython Bindings Instructions
+# Cython Instructions
 
-## Context
+See [dpctl/AGENTS.md](/dpctl/AGENTS.md) for conventions and patterns.
 
-Cython files in dpctl provide the bridge between Python and the C/C++ SYCL interface. They wrap SYCL runtime objects as Python extension types.
-
-## File Types
-
-| Extension | Purpose |
-|-----------|---------|
-| `.pyx` | Implementation files (compiled to C++) |
-| `.pxd` | Declaration files (like C headers) |
-| `.pxi` | Include files (textually included) |
-
-## Required Directives
-
-Every `.pyx` file must start with (after license header):
+## Quick Reference
 
+### Required Directives (after license header)
 ```cython
 # distutils: language = c++
 # cython: language_level=3
 # cython: linetrace=True
 ```
 
-## Import Conventions
-
-### cimport vs import
-
-```cython
-# cimport - for C-level declarations (compile-time)
-from cpython cimport pycapsule
-from cpython.mem cimport PyMem_Free, PyMem_Malloc
-from ._backend cimport DPCTLSyclDeviceRef, DPCTLDevice_Create
-
-# import - for Python-level usage (runtime)
-import numpy as np
-from . import _device_selection
-```
-
-### Import Order
-1. Standard library cimports
-2. Third-party cimports
-3. Local cimports (with `# noqa: E211` if needed)
-4. Blank line
-5. Standard library imports
-6. Third-party imports
-7. Local imports
-
-## Extension Type Pattern
-
-```cython
-cdef class SyclDevice:
-    """
-    Python wrapper for sycl::device.
-
-    Docstring describing the class.
-    """
-    # C-level attribute (not accessible from Python)
-    cdef DPCTLSyclDeviceRef _device_ref
-
-    def __cinit__(self, filter_string=None):
-        """
-        Called before __init__, handles C memory allocation.
-        Must not raise Python exceptions that leave C state invalid.
-        """
-        if filter_string is not None:
-            self._device_ref = DPCTLDevice_CreateFromSelector(...)
-        else:
-            self._device_ref = NULL
-
-    def __dealloc__(self):
-        """
-        Called during garbage collection. Clean up C resources.
-        """
-        if self._device_ref is not NULL:
-            DPCTLDevice_Delete(self._device_ref)
-
-    cdef DPCTLSyclDeviceRef get_device_ref(self):
-        """
-        Internal method for C-level access.
-        Not visible from Python.
-        """
-        return self._device_ref
-
-    @property
-    def name(self):
-        """Python property wrapping C getter."""
-        cdef const char *name_ptr = DPCTLDevice_GetName(self._device_ref)
-        if name_ptr is NULL:
-            raise RuntimeError("Failed to get device name")
-        try:
-            return name_ptr.decode("utf-8")
-        finally:
-            DPCTLCString_Delete(name_ptr)
-```
-
-## Memory Management
-
-### Rule: Always Clean Up in __dealloc__
-
-```cython
-def __dealloc__(self):
-    # Check for NULL before deleting
-    if self._queue_ref is not NULL:
-        DPCTLQueue_Delete(self._queue_ref)
-```
-
-### Ownership Annotations
-
-Match C API annotations:
-- `__dpctl_give` - Caller receives ownership, must delete
-- `__dpctl_take` - Function takes ownership, don't use after
-- `__dpctl_keep` - Function only observes, doesn't take ownership
-
-```cython
-cdef void example():
-    # Receives ownership (__dpctl_give) - must delete
-    cdef DPCTLSyclEventRef event = DPCTLQueue_Submit(...)
-
-    # ... use event ...
-
-    # Clean up owned resource
-    DPCTLEvent_Delete(event)
-```
-
-### GIL Management
-
-Release GIL for blocking C operations:
-
-```cython
-cdef void copy_with_wait(DPCTLSyclEventRef event):
-    with nogil:
-        DPCTLEvent_Wait(event)
-
-# Or for longer sections
-cdef void long_operation() nogil:
-    # Entire function runs without GIL
-    # Cannot call Python objects here
-    pass
-```
-
-## Error Handling
-
-### NULL Checks
-
-```cython
-cdef DPCTLSyclDeviceRef dref = DPCTLDevice_Create(...)
-if dref is NULL:
-    raise SyclDeviceCreationError("Failed to create device")
-```
-
-### Exception Safety
-
-```cython
-def create_something(self):
-    cdef SomeRef ref = SomeFunction()
-    if ref is NULL:
-        raise SomeError("Creation failed")
-    try:
-        # Operations that might raise
-        result = self._process(ref)
-    except:
-        # Clean up on exception
-        SomeDelete(ref)
-        raise
-    return result
-```
-
-## Backend Declarations (.pxd)
-
-```cython
-# _backend.pxd
-cdef extern from "syclinterface/dpctl_sycl_device_interface.h":
-    ctypedef void* DPCTLSyclDeviceRef
-
-    DPCTLSyclDeviceRef DPCTLDevice_Create(
-        DPCTLDeviceSelectorRef DSRef
-    ) nogil
-
-    void DPCTLDevice_Delete(
-        DPCTLSyclDeviceRef DRef
-    ) nogil
-
-    const char* DPCTLDevice_GetName(
-        DPCTLSyclDeviceRef DRef
-    ) nogil
-```
-
-## Include Files (.pxi)
-
-Used for shared code snippets:
-
-```cython
-# In main .pyx file
-include "_sycl_usm_array_interface_utils.pxi"
-```
-
-## Common Patterns
-
-### Property with C String Return
-
-```cython
-@property
-def driver_version(self):
-    cdef const char* ver = DPCTLDevice_GetDriverVersion(self._device_ref)
-    if ver is NULL:
-        return ""
-    try:
-        return ver.decode("utf-8")
-    finally:
-        DPCTLCString_Delete(ver)
-```
-
-### Capsule for Opaque Pointers
-
-```cython
-def get_capsule(self):
-    """Return PyCapsule containing C pointer."""
-    if self._device_ref is NULL:
-        return None
-    return pycapsule.PyCapsule_New(
-        <void*>self._device_ref,
-        "SyclDeviceRef",
-        NULL  # No destructor - we manage lifetime
-    )
-```
-
-### Type Checking
-
-```cython
-def some_method(self, other):
-    if not isinstance(other, SyclDevice):
-        raise TypeError(
-            f"Expected SyclDevice, got {type(other).__name__}"
-        )
-    cdef SyclDevice other_dev = <SyclDevice>other
-    # Now can access other_dev._device_ref
-```
+### Key Rules
+- `cimport` for C-level declarations, `import` for Python
+- Store C refs as `_*_ref`, clean up in `__dealloc__`
+- Use `with nogil:` for blocking C operations
+- Check NULL before using C API returns

.github/instructions/dpctl.instructions.md

@@ -3,133 +3,24 @@ applyTo:
   - "**/*.py"
   - "**/*.pyx"
   - "**/*.pxd"
-  - "**/*.pxi"
   - "**/*.cpp"
   - "**/*.hpp"
   - "**/*.h"
-  - "**/*.c"
 ---
 
 # DPCTL General Instructions
 
-## Project Context
+See [/AGENTS.md](/AGENTS.md) for project overview and architecture.
 
-DPCTL (Data Parallel Control) is a Python SYCL binding library for heterogeneous computing. It provides:
-- Python wrappers for SYCL runtime objects (devices, queues, contexts)
-- Array API-compliant tensor operations (`dpctl.tensor`)
-- USM memory management (`dpctl.memory`)
-- Kernel compilation (`dpctl.program`)
+## Key References
 
-## License Header Requirement
+- **Code style:** See `.pre-commit-config.yaml` for tool versions, `.clang-format` for C++ style
+- **License:** Apache 2.0 with Intel copyright - see existing files for header format
+- **Directory guides:** Each major directory has its own `AGENTS.md`
 
-**All source files must include the Apache 2.0 license header.**
+## Critical Rules
 
-### Python/Cython Files
-```python
-#                      Data Parallel Control (dpctl)
-#
-# Copyright 2020-2025 Intel Corporation
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#    http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-```
-
-### C/C++ Files
-```cpp
-//===-- filename.hpp - Brief description              -*-C++-*-===//
-//
-//                      Data Parallel Control (dpctl)
-//
-// Copyright 2020-2025 Intel Corporation
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// ...
-//===----------------------------------------------------------------------===//
-```
-
-## Code Style
-
-### Python
-- **Formatter:** Black (line length 80)
-- **Import sorting:** isort
-- **Linting:** flake8
-- **Max line length:** 80 characters
-
-### C/C++
-- **Formatter:** clang-format (LLVM-based)
-- **Indent:** 4 spaces
-- **Brace style:** Break before functions, classes, namespaces
-
-## Naming Conventions
-
-### Python/Cython
-- Classes: `PascalCase` (e.g., `SyclDevice`, `SyclQueue`)
-- Functions/methods: `snake_case` (e.g., `get_device_info`)
-- Private: prefix with `_` (e.g., `_validate_queue`)
-- Constants: `UPPER_SNAKE_CASE`
-
-### C API (libsyclinterface)
-- Functions: `DPCTL<Class>_<Method>` (e.g., `DPCTLDevice_Create`)
-- Types: `DPCTL<Class>Ref` (e.g., `DPCTLSyclDeviceRef`)
-- Macros: `DPCTL_` prefix
-
-### C++ Kernels
-- Functors: `<Operation>Functor` (e.g., `AddFunctor`)
-- Kernel classes: `<operation>_krn` suffix
-- Namespaces: `dpctl::tensor::kernels`
-
-## Error Handling
-
-### Python Exceptions
-- `SyclDeviceCreationError` - Device creation failed
-- `SyclQueueCreationError` - Queue creation failed
-- `ExecutionPlacementError` - Queue mismatch between arrays
-- `TypeError`, `ValueError` - Standard Python errors for invalid input
-
-### C API Error Handling
-- Return `NULL` for failed object creation
-- Use `error_handler_callback` for async errors
-- Check return values before using
-
-## Device Compatibility
-
-**Warning:** Not all SYCL devices support all data types.
-
-- **fp64 (double):** Check `device.has_aspect_fp64`
-- **fp16 (half):** Check `device.has_aspect_fp16`
-
-Always use `skip_if_dtype_not_supported()` in tests.
-
-## Common Patterns
-
-### Queue Validation
-```python
-def some_operation(x, y):
-    exec_q = dpctl.utils.get_execution_queue([x.sycl_queue, y.sycl_queue])
-    if exec_q is None:
-        raise ExecutionPlacementError("...")
-```
-
-### Resource Cleanup
-```python
-cdef class SyclDevice:
-    cdef DPCTLSyclDeviceRef _device_ref
-
-    def __dealloc__(self):
-        DPCTLDevice_Delete(self._device_ref)
-```
-
-### GIL Release for Blocking Operations
-```cython
-with nogil:
-    DPCTLEvent_Wait(event_ref)
-```
+1. **Device compatibility:** Not all devices support fp64/fp16 - check capabilities
+2. **Queue consistency:** All arrays in an operation must share compatible queues
+3. **Resource cleanup:** Always clean up C resources in `__dealloc__`
+4. **NULL checks:** Always check C API returns before use